Contents Previous Next

Java 3D API Specification


C H A P T E R7
Node Component Objects




NODE component objects include the actual geometry and appearance attributes used to render the geometry.

7.1 Node Component Objects-Attributes

Node objects by themselves do not fully specify their exact semantics. They contain information that further refines their exact meaning. Some of that information is specified as an attribute and an associated floating-point or integer value. However, in many cases, that information consists of references to more complex entities called node component objects. Node component objects encapsulate related state information in a single entity. See Figure 7-1.

7.1.1 Appearance Object

The Appearance object is a component object of a Shape3D node that defines all rendering state for that shape node. If the Appearance object in a Shape3D node is null, default values will be used for all rendering state attributes.

Constants

The Appearance component object defines the following flags. 

public static final int ALLOW_MATERIAL_READ
public static final int ALLOW_MATERIAL_WRITE
public static final int ALLOW_TEXTURE_READ
public static final int ALLOW_TEXTURE_WRITE
public static final int ALLOW_TEXGEN_READ
public static final int ALLOW_TEXGEN_WRITE
public static final int ALLOW_TEXTURE_ATTRIBUTES_READ
public static final int ALLOW_TEXTURE_ATTRIBUTES_WRITE
public static final int ALLOW_COLORING_ATTRIBUTES_READ
public static final int ALLOW_COLORING_ATTRIBUTES_WRITE
public static final int ALLOW_TRANSPARENCY_ATTRIBUTES_READ
public static final int ALLOW_TRANSPARENCY_ATTRIBUTES_WRITE
public static final int ALLOW_RENDERING_ATTRIBUTES_READ
public static final int ALLOW_RENDERING_ATTRIBUTES_WRITE
public static final int ALLOW_POLYGON_ATTRIBUTES_READ
public static final int ALLOW_POLYGON_ATTRIBUTES_WRITE
public static final int ALLOW_LINE_ATTRIBUTES_READ
public static final int ALLOW_LINE_ATTRIBUTES_WRITE
public static final int ALLOW_POINT_ATTRIBUTES_READ
public static final int ALLOW_POINT_ATTRIBUTES_WRITE

These flags, when enabled using the setCapability method, allow an application to invoke methods that respectively read and write its Material, Texture, TexGen texture attributes, transparency or other rendering parameters. These capability flags are enforced only when the object is part of a live or compiled scene graph.

Constructors

The Appearance object has the following constructor: 

public Appearance()

Construct and initialize a material object. All component object references are initialized to null.

The default values are as follows:

color: white (1,1,1)
texture environment mode: TEXENV_REPLACE
texture environment color: white (1,1,1,1)
depth test enable: true
shade model: SHADE_SMOOTH
polygon mode: POLYGON_FILL
transparency enable: false
transparency mode: FASTEST
cull face: CULL_BACK
point size: 1.0
line width: 1.0
line pattern: PATTERN_SOLID
point antialiasing enable: false
line antialiasing enable: false

Methods

The Appearance object has the following methods. 

public final void setMaterial(Material material)
public final Material getMaterial()

The Material object specifies the desired material properties used for lighting. Setting it to null disables lighting. 

public final void setTexture(Texture texture)
public final Texture getTexture()

The texture object specifies the desired texture map and texture parameters. Setting it to null disables texture mapping. 

public final void setTextureAttributes(TextureAttributes 
       textureAttributes)
public final TextureAttributes getTextureAttributes()

The set method sets the textureAttributes object to the specified object. Setting the texture attributes to null results in default attribute use. The get method retrieves the current textureAttributes object. 

public final void setColoringAttributes(ColoringAttributes 
       coloringAttributes)
public final ColoringAttributes getColoringAttributes()

The set method sets the coloringAttributes object to the specified object. Setting it to null results in default attribute use. The get method retrieves the current coloringAttributes object. 

public final void 
       setTransparencyAttributes(TransparencyAttributes 
       transparencyAttributes)
public final TransparencyAttributes getTransparencyAttributes()

The set method sets the transparencyAttributes object to the specified object. Setting it to null results in default attribute use. The get method retrieves the current transparencyAttributes object. 

public final void setRenderingAttributes(RenderingAttributes 
       renderingAttributes)
public final RenderingAttributes getRenderingAttributes()

The set method sets the renderingAttributes object to the specified object. Setting it to null results in default attribute use. The get method retrieves the current renderingAttributes object. 

public final void setPolygonAttributes(PolygonAttributes 
       polygonAttributes)
public final PolygonAttributes getPolygonAttributes()

The set method sets the polygonAttributes object to the specified object. Setting it to null results in default attribute use. The get method retrieves the current polygonAttributes object. 

public final void setLineAttributes(LineAttributes 
       lineAttributes)
public final LineAttributes getLineAttributes()

The set method sets the lineAttributes object to the specified object. Setting it to null results in default attribute use. The get method retrieves the current lineAttributes object. 

public final void setPointAttributes(PointAttributes 
       pointAttributes)
public final PointAttributes getPointAttributes()

The set method sets the pointAttributes object to the specified object. Setting it to null results in default attribute use. The get method retrieves the current pointAttributes object. 

public final void setTexCoordGeneration(TexCoordGeneration 
       texCoordGeneration)
public final TexCoordGeneration getTexCoordGeneration()

The set method sets the texCoordGeneration object to the specified object. Setting it to null disables the texture coordinate generation. The get method retrieves the current texCoordGeneration object. 

public NodeComponent cloneNodeComponent()

This method creates a new Appearance object. Called from a Leaf node's duplicateNode method. 

public void duplicateNodeComponent(Node originalNode)

This method copies the information found in originalNode to the current node. This routine is called as part of the cloneTree operation.

7.1.2 ColoringAttributes Object

The ColoringAttributes object defines attributes that apply to color mapping.

Constants
public static final int ALLOW_COLOR_READ
public static final int ALLOW_COLOR_WRITE
public static final int ALLOW_SHADE_MODEL_READ
public static final int ALLOW_SHADE_MODEL_WRITE

These flags, when enabled using the setCapability method, allow an application to invoke methods that respectively read and write its color component and shade model component information.

Constructors
public ColoringAttributes()
public ColoringAttributes(Color3f color, int shadeModel)
public ColoringAttributes(float red, float green, float blue, 
       int  shadeModel)

These constructors create a ColoringAttributes object with the specified values.

Methods
public final void setColor(Color3f color)
public final void setColor(float r, float g, float b)
public final void getColor(Color3f color)

These methods set and retrieve the intrinsic color of this ColoringAttributes component object. This color is used when lighting is disabled or when the material is null. 

public final void setShadeModel(int shadeModel)
public final int getShadeModel()

These methods set and retrieve the shade mode for this ColoringAttributes component object. The shade mode is one of the following: 

public NodeComponent cloneNodeComponent()

This method creates a new ColoringAttributes object. This method is called from a Leaf node's duplicateNode method. 

public void duplicateNodeComponent(Node originalNode)

This method copies the information found in originalNode to the current node. This method is called as part of the cloneTree operation.

7.1.3 LineAttributes Object

The LineAttributes object defines all rendering state that can be set as a component object of a Shape3D node.

Constants
public static final int PATTERN_SOLID
public static final int PATTERN_DASH
public static final int PATTERN_DOT
public static final int PATTERN_DASH_DOT

These flags define the line type. The definitions of these flags are as follows:

Constructors
public LineAttributes()
public LineAttributes(float lineWidth, int linePattern, 
       boolean  lineAntialiasing)

The first constructor creates a LineAttributes object with default values. The second constructor creates a LineAttributes object with specified values of line width, pattern, and whether antialiasing is enabled or disabled.

Methods
public final void setLineWidth(float lineWidth)
public final float getLineWidth()

These methods respectively set and retrieve the line width, in pixels, for this LineAttributes component object. 

public final void setLinePattern(int linePattern)
public final int getLinePattern()

These methods respectively set and retrieve the line pattern for this LineAttributes component object. The linePattern value describes the line patters to be used, and is one of: PATTERN_SOLID, PATTERN_DASH, PATTERN_DOT, or PATTERN_DASH_DOT. 

public final void setLineAntialiasingEnable(boolean state)
public final boolean getLineAntialiasingEnable()

The set method enables or disables line antialiasing for this LineAttributes component object. The get method retrieves the state of the line antialiasing flag. The flag is true if line antialiasing is enabled, false if line antialiasing is disabled. 

public NodeComponent cloneNodeComponent()
public void duplicateNodeComponent(NodeComponent originalNode)

The first method creates a new LineAttributes object; this method is called from a Leaf node's duplicateNode method. The second method copies the information found in originalNode to the current node; this method is called as part of the cloneTree operation.

7.1.4 PointAttributes Object

The PointAttributes object defines all rendering state that can be set as a component object of a Shape3D node.

Constructors
public PointAttributes()
public PointAttributes(float pointSize, 
       boolean  pointAntialiasing)

These constructors create a new PointAttributes object.

Methods
public final void setPointSize(float pointSize)
public final float getPointSize()

These methods set and retrieve the point size, in pixels, for this Appearance component object. 

public final void setPointAntialiasingEnable(boolean state)
public final boolean getPointAntialiasingEnable()

These methods set and retrieve the state of the point antialiasing flag for this Appearance component object. The flag is true if point antialiasing is enabled, false if point antialiasing is disabled. 

public NodeComponent cloneNodeComponent()
public void duplicateNodeComponent(NodeComponent originalNode)

The first method creates a new PointAttributes object; this method is called from a Leaf node's duplicateNode method. The second method copies the information found in originalNode to the current node; this method is called as part of the cloneTree operation.

7.1.5 PolygonAttributes Object

The PolygonAttributes object defines all rendering state that can be set as a component object of a Shape3D node.

Constructors
public PolygonAttributes()
public PolygonAttributes(int polygonMode, int cullFace, 
       float  polygonOffset)

These constructors create a new PolygonAttributes object.

Methods
public final void setCullFace(int cullFace)
public final int getCullFace()

These methods set and retrieve the face culling flag for this PolygonAttributes component object. The face culling flag is one of the following: 

public final void setPolygonMode(int polygonMode)
public final int getPolygonMode()

These methods set and retrieve the polygon rasterization mode for this Appearance component object. The polygon rasterization mode is one of the following: 

public final void setPolygonOffset(float polygonOffset)
public final float getPolygonOffset()

These methods set and retrieve the polygon offset. This screen space offset is added to the final, device coordinate Z value of polygon primitives. 

public NodeComponent cloneNodeComponent()
public void duplicateNodeComponent(NodeComponent originalNode)

The first method creates a new PolygonAttributes object; this method is called from a Leaf node's duplicateNode method. The second method copies the information found in originalNode to the current node; this method is called as part of the cloneTree operation.

7.1.6 RenderingAttributes Object

The RenderingAttributes object defines all rendering state that can be set as a component object of a Shape3D node.

Constants
public static final int ALLOW_ALPHA_TEST_VALUE_READ
public static final int ALLOW_ALPHA_TEST_VALUE_WRITE
public static final int ALLOW_ALPHA_TEST_FUNCTION_READ
public static final int ALLOW_ALPHA_TEST_FUNCTION_WRITE

These flags, when enabled using the setCapability method, allow an application to invoke methods that respectively read and write its individual test value and function information.

Constructors
public RenderingAttributes()
public RenderingAttributes(boolean depthBufferEnable, 
       boolean  depthBufferWriteEnable, float alphaTestValue, 
       int  alphaTestFunction)

These constructors create a new RenderingAttributes object.

Methods
public final void setDepthBufferEnable(boolean state)
public final boolean getDepthBufferEnable()

These methods set and retrieve the depth buffer enable flag for this RenderAttributes component object. The flag is true if the depth buffer mode is enabled, false if disabled. 

public final void setDepthBufferWriteEnable(boolean state)
public final boolean getDepthBufferWriteEnable()

These methods set and retrieve the depth buffer write enable flag for this RenderAttributes component object. The flag is true if the depth buffer mode is writable, false if the depth buffer is read-only. 

public final void setAlphaTestValue(float value)
public final float getAlphaTestValue()

These methods set and retrieve the alpha test value used by alpha test function. This value is compared to the alpha value of each rendered pixel. 

public final void setAlphaTestFunction(int function)
public final int getAlphaTestFunction()

These methods set and retrieve the alpha test function. The alpha test function is one of the following: 

public NodeComponent cloneNodeComponent()
public void duplicateNodeComponent(NodeComponent originalNode)

The first method creates a new RenderingAttributes object; this method is called from a Leaf node's duplicateNode method. The second method copies the information found in originalNode to the current node; this method is called as part of the cloneTree operation.

7.1.7 TextureAttributes Object

The TextureAttributes object defines attributes that apply to texture mapping.

Constants
public static final int ALLOW_MODE_READ
public static final int ALLOW_MODE_WRITE
public static final int ALLOW_BLEND_COLOR_READ
public static final int ALLOW_BLEND_COLOR_WRITE
public static final int ALLOW_TRANSFORM_READ
public static final int ALLOW_TRANSFORM_WRITE

These flags, when enabled using the setCapability method, allow an application to invoke methods that respectively read and write its individual component field information.

Constructors
public TextureAttributes()
public TextureAttributes(int textureMode, Transform3D transform, 
       Color4f textureBlendColor, int perspCorrectionMode)

These constructors create a new TextureAttributes object.

Methods
public final void setTextureMode(int textureMode)
public final int getTextureMode()

These methods set and retrieve the texture mode parameter for this TextureAttributes component object. The texture mode is one of the following: 

public final void setTextureBlendColor(Color4f textureBlendColor)
public final void setTextureBlendColor(float r, float g, float  b, 
       float a)
public final void getTextureBlendColor(Color4f textureBlendColor)

These methods set and retrieve the texture blend color for this TextureAttributes component object. The texture blend color is used when the texture mode parameter is BLEND. 

public final void setTextureTransform(Transform3D transform)
public final void getTextureTransform(Transform3D transform)

These methods set and retrieve the texture transform object used to transform texture coordinates. A copy of the specified Transform3D object is stored in this TextureAttributes object. 

public final void setPerspectiveCorrectionMode(int mode)
public final int getPerspectiveCorrectionMode()

These methods set and retrieve the perspective correction mode to be used for color and texture coordinate interpolation. The perspective correction mode is one of the following: 

public NodeComponent cloneNodeComponent()
public void duplicateNodeComponent(NodeComponent originalNode)

The first method creates a new TextureAttributes object; this method is called from a Leaf node's duplicateNode method. The second method copies the information found in originalNode to the current node; this method is called as part of the cloneTree operation.

7.1.8 TransparencyAttributes Object

The TransparencyAttributes object defines all attributes affecting transparency of the object.

Constants
public static final int ALLOW_MODE_READ
public static final int ALLOW_MODE_WRITE
public static final int ALLOW_VALUE_READ
public static final int ALLOW_VALUE_WRITE

These flags, when enabled using the setCapability method, allow an application to invoke methods that respectively read and write its individual component field information.

Constructors
public TransparencyAttributes()
public TransparencyAttributes(int tMode, float tVal)

These constructors create a new TransparencyAttributes object.

Methods
public final void setTransparencyMode(int transparencyMode)
public final int getTransparencyMode()

These methods set and retrieve the transparency mode for this Appearance component object. The transparency mode is one of the following: 

public final void setTransparency(float transparency)
public final float getTransparency()

These methods set and retrieve this Appearance object's transparency value. The transparency value is in the range [0.0, 1.0] with 0.0 being fully opaque and 1.0 being fully transparent. 

public NodeComponent cloneNodeComponent()
public void duplicateNodeComponent(NodeComponent originalNode)

The first method creates a new TransparencyAttributes object; this method is called from a Leaf node's duplicateNode method. The second method copies the information found in originalNode to the current node; this method is called as part of the cloneTree operation.

7.1.9 Material Object

The Material object is a component object of an Appearance object that defines the material properties used when lighting is enabled. If the Material object in an Appearance object is null, lighting is disabled for all nodes that use that Appearance object.

Constants

The Material object defines two flags. 

public static final int ALLOW_COMPONENT_READ
public static final int ALLOW_COMPONENT_WRITE

These flags, when enabled using the setCapability method, allow an application to invoke methods that respectively read and write its individual component field information.

Constructors

The Material object has the following constructors: 

public Material()

Construct and initialize a material object using default values for all attributes. The default values are as follows:

ambient color: 0.2, 0.2, 0.2
emissive color: black (0,0,0)
diffuse color: white (1,1,1)
specular color: white (1,1,1)
shininess: 0.0 

public Material(Color3f ambientColor, Color3f emmissiveColor, 
       Color3f diffuseColor, Color3f specularColor, 
       float  shininess)

Construct and initialize a new material object using the specified parameters. The ambient color, emissive color, diffuse color, specular color, and shininess parameters are specified.

Methods

The Material object has the following methods. 

public final void setAmbientColor(Color3f color)
public final void setAmbientColor(float r, float g, float b)
public final void getAmbientColor(Color3f color)

This parameter specifies this material's ambient color - how much ambient light is reflected by the material's surface. 

public final void setEmissiveColor(Color3f color)
public final void setEmissiveColor(float r, float g, float b)
public final void getEmissiveColor(Color3f color)

This parameter specifies the color of light, if any, that the material emits. This color is added to the color produced by applying the lighting equation. 

public final void setDiffuseColor(Color3f color)
public final void setDiffuseColor(float r, float g, float b)
public final void setDiffuseColor(float r, float g, float b, 
       float a)
public final void getDiffuseColor(Color3f color)

This parameter specifies the color of the material when illuminated by a light source. In addition to the diffuse color (red, green, and blue), the alpha value is used to specify transparency such that transparency = (1 - alpha). 

public final void setSpecularColor(Color3f color)
public final void setSpecularColor(float r, float g, float b)
public final void getSpecularColor(Color3f color)

This parameter specifies the specular highlight color of the material. 

public final void setShininess(float shininess)
public final float getShininess()

This parameter specifies a material specular scattering exponent, or shininess. It takes a floating point number in the range [0.0, 128.0] with 0.0 being not shiny and 128.0 being very shiny. 

public final void setLightingEnable(boolean state)
public final boolean getLightingEnable()

These methods set and retrieve the current state of the lighting enable flag (true or false) for this Appearance component object. 

public NodeComponent cloneNodeComponent()
public void duplicateNodeComponent(NodeComponent originalNode)

The first method creates a new Material object; this method is called from a Leaf node's duplicateNode method. The second method copies the information found in originalNode to the current node; this method is called as part of the cloneTree operation. 

public String toString()

This method returns a String representation of this Material's values. If the scene graph is live, only those values with their Capability bit set will be displayed.

7.1.10 Texture Object

The Texture object is a component object of an Appearance object that defines the texture properties used when texture mapping is enabled. If the Texture object in an Appearance object is null, then texture mapping is disabled for all nodes that use that Appearance object. The Texture object is an abstract class. As such, all texture objects must be created as either a Texture2D object or a Texture3D object.

Constructors

The Texture object has the following constructor. 

public Texture()

Constructs a Texture object using default values. The default values are as follows:

boundaryModeS: WRAP
boundaryModeT: WRAP
minification filter: BASE_LEVEL_POINT
magnification filter: BASE_LEVEL_POINT
boundary color: black (0,0,0,0)
texture image: null 

public Texture(int mipmapMode, int format, int width, int  height)

Constructs an empty Texture object with specified mipmapMode format, width, and height. Image at level 0 must be set by the application using the setImage method. The mipmapMode can be one of the following:

The format is the data of Textures saved in this object. The format can be one of the following:

Methods

The Texture object has the following methods. 

public final void setBoundaryModeS(int boundaryModeS)
public final int getBoundaryModeS()
public final void setBoundaryModeT(int boundaryModeT)
public final int getBoundaryModeT()

These parameters specify the boundary mode for the S and T coordinates in this texture object. The boundary mode is as follows: 

public final void setMinFilter(int minFilter)
public final int getMinFilter()

This parameter specifies the minification filter function. This function is used when the pixel being rendered maps to an area greater than one texel. The minification filter is one of the following: 

public final void setMagFilter(int magFilter)
public final int getMagFilter()

This parameter specifies the magnification filter function. This function is used when the pixel being rendered maps to an area less than or equal to one texel. Values are one of the following: 

public final void setImage(int level, ImageComponent image)
public final ImageComponent getImage(int level)

These methods set and retrieve a specified mipmap level. Level 0 is the base level. 

public final void setBoundaryColor(Color4f boundaryColor)
public final void setBoundaryColor(float r, float g, float b, 
       float a)
public final void getBoundaryColor(Color4f boundaryColor)

This parameter specifies the texture boundary color for this texture object. The texture boundary color is used when boundaryModeS or boundaryModeT is set to CLAMP. 

public final void setEnable(boolean state)
public final boolean getEnable()

These methods set and retrieve the state of texture mapping for this Texture object. A value of true means that texture mapping is enabled, false means that texture mapping is disabled. 

public final void setMipMapMode(int mipmapMode)
public final int getMipMapMode()

These methods set and retrieve the mipmap mode for texture mapping for this Texture object. The mipmap mode is one of the following: BASE_LEVEL or MULTI_LEVEL_MIPMAP.

7.1.11 Texture2D Object

The Texture2D object is a subclass of the Texture class. It extends the Texture class by adding a constructor for setting a 2D texture image.

Constructors

The Texture2D object has the following constructors. 

public Texture2D()
public Texture2D(int mipmapMode, int format, int width, 
       int  height)

Construct and initialize a Texture2D object. The first form uses default values for all attributes. The second form uses the specified attributes. The mipmapMode parameter is one of BASE_LEVEL or MULTI_LEVEL_MIPMAP. The format parameter is one of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, or RGBA.

Methods
public NodeComponent cloneNodeComponent()
public void duplicateNodeComponent(NodeComponent originalNode)

The first method creates a new Texture2D object; this method is called from a Leaf node's duplicateNode method. The second method copies the information found in originalNode to the current node; this method is called as part of the cloneTree operation.

7.1.12 Texture3D Object

The Texture3D object is a subclass of the Texture class. It extends the Texture class by adding a third texture coordinate and by adding a constructor for setting a 3D texture image.

Constructors

The Texture3D object has the following constructors. 

public Texture3D()
public Texture3D(int mipmapMode, int format, int width, 
       int  height, int depth)

Construct and initialize a Texture3D object. The first form uses default values for all attributes. The second form uses the specified attributes. The mipmapMode parameter is one of BASE_LEVEL or MULTI_LEVEL_MIPMAP. The format parameter is one of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, or RGBA. The default values for a Texture3D object are as follows:

Methods

The Texture3D object has the following methods. 

public final void setBoundaryModeR(int boundaryModeR)
public final int getBoundaryModeR()

This parameter specifies the boundary mode for the R coordinates in this texture object. The boundary mode is as follows: 

public NodeComponent cloneNodeComponent()
public void duplicateNodeComponent(NodeComponent originalNode)

The first method creates a new Texture3D object; this method is called from a Leaf node's duplicateNode method. The second method copies the information found in originalNode to the current node; this method is called as part of the cloneTree operation.

7.1.13 TexCoordGeneration Object

The TexCoordGeneration object is a component object of an Appearance object that defines the parameters used when texture coordinate generation is enabled. If the TexGen object in an Appearance object is null, then texture coordinate generation is disabled for all nodes that use that Appearance object.

Constants

The TexGen object specifies the following variables: 

public final static int OBJECT_LINEAR

Generates texture coordinates as a linear function in object coordinates. 

public final static int EYE_LINEAR

Generates texture coordinates as a linear function in eye coordinates. 

public final static int SPHERE_MAP

Generates texture coordinates using a spherical reflection mapping in eye coordinates. 

public final static int TEXTURE_COORDINATE_2

Generates 2D texture coordinates (S and T). 

public final static int TEXTURE_COORDINATE_3

Generates 3D texture coordinates (S, T, and R).

Constructors

The TexGen object has the following constructors: 

public TexCoordGeneration()
public TexCoordGeneration(int genMode, int format)
public TexCoordGeneration(int genMode, int format, 
       Vector4f  planeS)
public TexCoordGeneration(int genMode, int format, 
       Vector4f  planeS, Vector4f planeT)
public TexCoordGeneration(int genMode, int format, 
       Vector4f  planeS, Vector4f planeT, Vector4f planeR)

The first form constructs a TexGen object using default values for all state variables. The other forms construct a TexGen object by initializing the specified fields. Default values are used for those state variables not specified in the constructor. The parameters are as follows:

Default values for parameters that are not specified are as follows:

genMode: OBJECT_LINEAR
format: TEXTURE_COORDINATE_2
planeS: (1, 0, 0, 0)
planeT: (0, 1, 0, 0)
planeR: (0, 0, 0, 0)

Methods

The TexGen object has the following methods. 

public final void setEnable(boolean state)
public final boolean getEnable()

This parameter enables or disables texture coordinate generation for this Appearance component object. The value is true if texture coordinate generation is enabled, false if texture coordinate generation is disabled. 

public final void setFormat(int format)
public final int getFormat()

This parameter specifies the format, or dimension of the generated texture coordinates. The format values are one of TEXTURE_COORDINATE_2 or TEXTURE_COORDINATE_3. 

public final void setGenMode(int genMode)
public final int getGenMode()

This parameter specifies the texture coordinate generation mode. Values are one of OBJECT_LINEAR, EYE_LINEAR, or SPHERE_MAP. 

public final void setPlaneS(Vector4f planeS)
public final void getPlaneS(Vector4f planeS)

This parameter specifies the S coordinate plane equation. This plane equation is used to generate the S coordinate in OBJECT_LINEAR and EYE_LINEAR texture generation modes. 

public final void setPlaneT(Vector4f planeT)
public final void getPlaneT(Vector4f planeT)

This parameter specifies the T coordinate plane equation. This plane equation is used to generate the T coordinate in OBJECT_LINEAR and EYE_LINEAR texture generation modes. 

public final void setPlaneR(Vector4f planeR)
public final void getPlaneR(Vector4f planeR)

This parameter specifies the R coordinate plane equation. This plane equation is used to generate the R coordinate in OBJECT_LINEAR and EYE_LINEAR texture generation modes. 

public NodeComponent cloneNodeComponent()
public void duplicateNodeComponent(NodeComponent originalNode)

The first method creates a new TexCoordGeneration object; this method is called from a Leaf node's duplicateNode method. The second method copies the information found in originalNode to the current node; this method is called as part of the cloneTree operation.

7.1.14 MediaContainer Object

The MediaContainer object is a component object of a Sound node that defines the sound data associated with a Sound node. This component object's fields references a Java Media Framework Player (which contains audio data), a Java Media Sound data container, or explicit sound sample data. Its fields include a cache flag and a URL path to sound data recognized by JavaSound (a proposed Java Media API) as a valid container that includes audio data. Eventually, when the JavaSound API is completed, the application can use JavaSound query methods to determine the format, precision, encoding and compression type, data length, and number of channels required for playback for a particular MediaContainer at the given URL path.

Constants

The MediaContainer object has the following flags. 

public static final int ALLOW_CACHE_READ
public static final int ALLOW_CACHE_WRITE
public static final int ALLOW_URL_READ
public static final int ALLOW_URL_WRITE

These flags, when enabled using the setCapability method, allow an application to invoke methods that read or write its cached flag and its URL string.

Constructors

The MediaContainer object has the following constructors: 

public MediaContainer()

Constructs and initializes a new MediaContainer object using the following default values:

cache data: false
URL: null 

public MediaContainer(String URL)

Constructs and initializes a new MediaContainer object using the specified URL path parameter and forcing the cache data flag to true.

Methods

The Sound object has the following methods. 

public final void setCacheEnable(boolean flag)
public final boolean getCacheEnable()

This parameter specifies whether this component contains a non-cached, reference to the sound data, or explicit cached sound data. 

public final void setURL(String path)
public final String getURL()

This parameter specifies the String path (URL) of the sound data associated with this component.

7.1.15 AuralAttributes Object

The AuralAttributes object is a component object of a Soundscape node that defines environmental audio parameters that affect sound rendering. These attributes include gain scale factor, atmospheric rolloff, and parameters controlling reverberation, distance frequency filtering, and velocity-activated Doppler effect.

7.1.15.1 Reverberation

Within Java 3D's simple model for auralization, there are three components to sound reverberation for a particular listening space:

None of these parameters are affected by sound position. Figure 7-2 shows the interaction of these parameters.

The reflection coefficient for reverberation is a single scale factor used to approximate the overall reflective or absorptive characteristics of the surfaces in a reverberation region the listener is in. This scale factor is applied to the sound's amplitude regardless of the sound's position. A value of 1.0 represents complete (unattenuated) sound reflection, while a value of 0.0 represents full absorption (reverberation is disabled).

The reverberation delay time is set either explicitly (in milliseconds), or implicitly by supplying an additional bounds volume (so the delay time can be calculated). The bounds of the reverberation space does not have to be the same as the application region of the Soundscape node using this object.

The reverberation order defines the number of reverberation (feedback) loop iterations to be executed while a sound is played. As long as the reflection coefficient is small enough, the reverberated sound decreases (as it would naturally) each successive iteration. A value of 0 creates a single echo (given that the reverb delay is long enough), while a value of -1 signifies that reverberation is to loop until it reaches an amplitude of effective zero (>60 dB or 1/1000 of sound amplitude). All other positive values are used as the number of loop iteration.

7.1.15.2 Doppler Effect

Doppler effect can be used to create a greater sense of movement of sound sources, and can help unambiguate front-back localization errors. The frequency of sound waves emanating from the source are lowered based on the speed of the source in relation to the listener, and the sound wave length.

The Doppler scale factor can be used to increase or reduce the change of frequency associated with normal Doppler calculation. To create this Doppler effect, the relative velocity (change in distance in the local coordinate system between the sound source and the listener over time, in meters per second) must be specified. This is non-zero even if the listener is moving but the sound is not.

Default values are assigned to all these audio rendering state attributes.

Constants

The AuralAttributes object has the following flags. 

public static final int ALLOW_ATTRIBUTE_GAIN_READ
public static final int ALLOW_ATTRIBUTE_GAIN_WRITE
public static final int ALLOW_ROLLOFF_READ
public static final int ALLOW_ROLLOFF_WRITE
public static final int ALLOW_REFLECTION_COEFFICIENT_READ
public static final int ALLOW_REFLECTION_COEFFICIENT_WRITE
public static final int ALLOW_REVERB_DELAY_READ
public static final int ALLOW_REVERB_DELAY_WRITE
public static final int ALLOW_REVERB_ORDER_READ
public static final int ALLOW_REVERB_ORDER_WRITE
public static final int ALLOW_DISTANCE_FILTER_READ
public static final int ALLOW_DISTANCE_FILTER_WRITE
public static final int ALLOW_DOPPLER_SCALE_FACTOR_READ
public static final int ALLOW_DOPPLER_SCALE_FACTOR_WRITE
public static final int ALLOW_DOPPLER_VELOCITY_READ
public static final int ALLOW_DOPPLER_VELOCITY_WRITE

These flags, when enabled using the setCapability method, allow an application to invoke methods that read or write its parameters.

Constructors

The AuralAttribute object has the following constructors: 

public AuralAttributes()

Constructs and initializes a new AuralAttributes object using the following default values:

attribute gain: 1.0
rolloff: 1.0
reflection coeff: 0.0
reverb delay: 0.0
reverb order: 0
distance filtering: null (no filtering performed)
doppler scale factor: 1.0
doppler velocity: 0.0 

public AuralAttributes(float gain, float rolloff, 
       float  reflectionCoefficient, float reverbDelay, 
       int  reverbOrder, Point2f[] distanceFilter, 
       float  dopplerScaleFactor, float dopplerVelocity)
public AuralAttributes(float gain, float rolloff, 
       float  reflectionCoefficient, float reverbDelay, 
       int  reverbOrder, float distance[], float frequencyCutoff, 
       float dopplerScaleFactor, float dopplerVelocity)

Construct and initialize a new AuralAttribute object using the specified parameters.

Methods

The AuralAttribute object has the following methods. 

public final void setAttributeGain(float gain)
public final float getAttributeGain()

This parameter specifies an amplitude scale factor applied to the sound. Valid values are 0.0. 

public final void setRolloff(float rolloff)
public final float getRolloff()

This scale factor is used to model simple atmospheric conditions that affect the speed of sound. Normal gain attenuation based on distance (specified in the local coordinate system) of the sound to listener is scaled by this single rolloff scale factor, thus increasing or decreasing the usual attenuation. Valid values are 0.0. Values > 1.0 increase the speed of sound, while values < 1.0 decrease its speed. 

public final void setReflectionCoefficient(float reflectionCoeff)
public final float getReflectionCoefficient()

This parameter specifies an average (cumulative) amplitude scale factor for all sound waves (independent of their frequencies) reflecting off surfaces within the activation region the listener is in. The range of values is 0.0 to 1.0. A value of 0.0 represents a fully-absorptive surface (no sound waves reflect off), while a value of 1.0 represents a fully-reflective surface (amplitude of sound waves reflecting off surfaces are not decreased). 

public final void setReverbDelay(float reverbDelay)
public final void setReverbDelay(Bounds reverbVolume)
public final float getReverbDelay()

This parameter specifies the delay time between each order of reflection while reverberation is being rendered. In the first form of setReverbDelay, an explicit delay time is given in milliseconds. In the second form, a reverberation bounds volume is specified, then the delay time is calculated becoming the new reverb time delay. A value for delay time of 0.0 disables reverberation. 

public final void setReverbOrder(int reverbOrder)
public final int getReverbOrder()

This parameter specifies the number of times reflections are added to reverberation being calculated. A value of -1 specifies an unbounded number of reverberations. 

public final void setDistanceFilter(Point2f[] attenuation)
public final void setDistanceFilter(float[] distance, 
       float[]  frequencyCutoff)
public final int getDistanceFilterLength()
public final void getDistanceFilter(Point2f[] attenuation)
public final void getDistanceFilter(float distance[], 
       float  frequencyCutoff[])

This parameter specifies a (distance, filter) attenuation pairs array. If this is not set then no distance filtering is performed (equivalent to using a distance filter of Sound.NO_FILTER for all distances). Currently, this filter is a low-pass cutoff frequency. This array of pairs defines a piece-wise linear slope for range of values. This attenuation array is similar to the PointSound node's distanceAttenuation pair array, except paired with distances in this list are frequency values. Using these pairs, distance-based low-pass frequency filtering can be applied during sound rendering. Distances, specified in the local coordinate system in meters, must be > 0. Frequencies (in Hz) must be > 0.

If the distance from the listener to the sound source is less than the first distance in the array, the first filter is applied to the sound source. This creates a spherical region around the listener within which a sound is uniformly attenuated by the first filter in the array. If the distance from the listener to the sound source is greater than the last distance in the array, the last filter is applied to the sound source.

The first form of setDistanceFilter takes these pairs of values as an array of Point2f. The second form accepts two separate arrays for these values. The distance and frequencyCutoff arrays should be of the same length. If the frequencyCutoff array length is greater than the distance array length, the frequencyCutoff array elements beyond the length of the distance array are ignored. If the frequencyCutoff array is shorter than the distance array, the last frequencyCutoff array value is repeated to fill an array of length equal to distance array.

getDistanceFilterLength method returns the length of the distance filter arrays. Arrays passed into getDistanceFilter methods should all be at least this size.

There are two methods for getDistanceFilter, one returning an array of points, the other returning separate arrays for each attenuation component.

Distance elements in this array of pairs is a monotonically-increasing set of floating point numbers measured from the location of the sound source. FrequencyCutoff elements in this list of pairs can be any positive float. While for most applications this list of values will usually be monotonically-decreasing, they do not have to be. 

public final void setDopplerScaleFactor(float dopplerScaleFactor)
public final float getDopplerScaleFactor()

This parameter specifies a scale factor applied to the velocity or wavelength portion of the Doppler-effect equation used during sound rendering. Valid values are 0.0. 

public final void setDopplerVelocity(float dopplerVelocity)
public final float getDopplerVelocity()

This parameter specifies the velocity of sound relative to the listener's position and velocity, which is used in the velocity and wavelength portion of the Doppler effect equation used during sound rendering.

7.1.16 ImageComponent Object

The ImageComponent classes are used for texture and background images. The ImageComponent object is an abstract class that is used to define 2D or 3D ImageComponent classes.

Constants

The ImageComponent object specifies the following variables, used to define 2D or 3D ImageComponent classes. These variables specify the format of the pixel data. 

public final static int FORMAT_RGB

Specifies that each pixel contains three 8-bit channels, one each for red, green, and blue. This is the same as FORMAT_RGB8. 

public final static int FORMAT_RGBA

Specifies that each pixel contains four 8-bit channels, one each for red, green, blue, and alpha. This is the same as FORMAT_RGBA8. 

public final static int FORMAT_RGB8

Specifies that each pixel contains three 8-bit channels, one each for red, green, and blue. This is the same as FORMAT_RGB. 

public final static int FORMAT_RGBA8

Specifies that each pixel contains four 8-bit channels, one each for red, green, blue, and alpha. This is the same as FORMAT_RGBA. 

public final static int FORMAT_RGB5

Specifies that each pixel contains three 5-bit channels, one each for red, green, and blue. 

public final static int FORMAT_RGB5_A1

Specifies that each pixel contains three 5-bit channels, one each for red, green, and blue and a 1-bit channel for alpha. 

public final static int FORMAT_RGB4

Specifies that each pixel contains three 4-bit channels, one each for red, green, and blue. 

public final static int FORMAT_RGBA4

Specifies that each pixel contains four 4-bit channels, one each for red, green, blue, and alpha. 

public final static int FORMAT_LUM4_ALPHA4

Specifies that each pixel contains two 4-bit channels, one each for luminance and alpha. 

public final static int FORMAT_LUM8_ALPHA8

Specifies that each pixel contains two 8-bit channels, one each for luminance and alpha. 

public static final int FORMAT_R3_G3_B2

Specifies that each pixel contains two 3-bit channels, one each for red and green, and a 2-bit channel for blue. 

public static final int FORMAT_CHANNEL8

Specifies that each pixel contains one 8-bit channel. The channel can be used for only luminance, alpha, or intensity.

Constructors

The ImageComponent object defines the following constructor. 

public ImageComponent(int format, int width, int height)

This constructor constructs and initializes a new ImageComponent object.

Methods

The ImageComponent object defines the following methods. 

public final int getWidth()
public final int getHeight()
public final int getFormat()

These methods retrieve the width, height, and format of this image component object.

7.1.17 ImageComponent2D Object

The ImageComponent2D class defines a 2D array of pixels, used for texture and background images.

Constructors

The ImageComponent2D object defines the following constructor. 

public ImageComponent2D(int format, int width, int height)
public ImageComponent2D(int format, Image image)

The first constructor constructs and initializes a 2D image component object using the specified format, width, and height. The second constructor constructs and initializes a 2D image component object using the specified format and buffered image. A copy of the image is made.

Methods

The ImageComponent2D object defines the following method. 

public void set(Image image)

This method copies the specified buffered image to this 2D image component object.

Note: The image must be completely loaded before calling this function. 
public final Image getImage()

This method retrieves a copy of the image in this ImageComponent2D object.

7.1.18 ImageComponent3D Object

The ImageComponent3D class defines a 3D array of pixels, used for texture images.

Constructors

The ImageComponent3D object defines the following constructor. 

public ImageComponent3D(int format, int width, int height, 
       int  depth)
public ImageComponent3D(int format, Image image[])

The first constructor constructs and initializes a 3D image component object using the specified format, width, height, and depth. The second constructor constructs and initializes a 3D image component object using the specified format and the buffered image array.

Methods

The ImageComponent3D object defines the following methods. 

public final int getDepth()

This method retrieves the depth of this 2D image component object. 

public final Image[] getImage()
public final Image getImage(int index)

These methods retrieve a copy of the images in this ImageComponenet3D object. 

public final void set(Image images[])
public final void set(int index, Image images)

The first method copies the specified array of BufferedImage objects to this 3D image component object. The second method copies the specified BufferedImage object to this 3D image component object at the specified index.

7.1.19 DepthComponent Object

The DepthComponent object is an abstract base class that defines a 2D array of depth (Z) values.

Constructors

The DepthComponent object defines the following constructors. 

public DepthComponent()
public DepthComponentFloat(int width, int height)

Constructs a new floating-point depth (z-buffer) component object. The second form constructs it using the specified width and height.

Methods
int getWidth()
int getHeight()

These methods get the width and height for this object.

7.1.20 DepthComponentFloat Object

The DepthComponentFloat object extends the DepthComponent object and defines a 2D array of depth (Z) values in floating point format in the range [0,1]. A value of 0.0 indicates the closest Z value to the user while a value of 1.0 indicates the farthest Z value.

Constructors

The DepthComponentFloat object defines the following constructor. 

public DepthComponentFloat(int width, int height)

Constructs a new floating-point depth (z-buffer) component object with the specified width and height.

Methods
public void setDepthData(float[] depthData)
public void getDepthData(float[] depthData)

These methods set and retrieve the specified depth data for this object.

7.1.21 DepthComponentInt Object

The DepthComponentInt object extends the DepthComponent object and defines a 2D array of depth (Z) values in integer format. Values are in the range [0,(2N) - 1], where N is the Z buffer pixel depth.

Constructors

The DepthComponentInt object defines the following constructor. 

public DepthComponentInt(int width, int height)

Constructs a new integer depth (z-buffer) component object with the specified width and height. 

public void setDepthData(int[] depthData)
public void getDepthData(int[] depthData)

These methods set and retrieve the specified depth data for this object.

7.1.22 DepthComponentNative Object

The DepthComponentNative object extends the DepthComponent object and defines a 2D array of depth (Z) values stored in the most efficient format for a particular device. Values are not accessible by the user and may only be used to read the Z values and subsequently write them back.

Constructors

The DepthComponentNative object defines the following constructor. 

public DepthComponentNative(int width, int height)

Constructs a new native depth (z-buffer) component object with the specified width and height.

7.1.23 Bounds Object

Bounds objects define three varieties of containing volumes. Java 3D uses these containing volumes to support various culling operations. The types of bounds include an axis-aligned-box volume, a spherical volume, and a bounding polytope.

Methods

The Bounds object defines the following methods. 

public abstract Object clone()

Clone this object. 

public abstract void set(Bounds boundsObject)

This method sets the value of this Bounds object to enclose the specified bounding object. 

public abstract boolean intersect(Point3d origin, 
       Point3d  direction)
public abstract boolean intersect(Point3d point)
public abstract boolean intersect(Bounds boundsObject)
public abstract boolean intersect(Bounds boundsObjects[])

These methods test for the intersection of this Bounds object with a ray, a point, another bounds object, or an array of bounds objects, respectively. 

public abstract void combine(Bounds boundsObject)
public abstract void combine(Bounds boundsObjects[])
public abstract void combine(Point3d point
public abstract void combine(Point3d points[])

These methods combine this Bounds object with a bounding object, an array of bounding objects, a point, or an array of points, respectively. 

public abstract void transform(Bounds bounds, Transform3D trans)
public abstract void transform(Transform3D trans)

The first method tranforms a Bounds object so that it bounds a volume which is the result of transforming the given bounding object with the given transform. The second method transforms the Bounds object by the given matrix. 

public abstract boolean isEmpty()

This method tests if any objects are in a Bounds.

7.1.24 BoundingBox Object

BoundingBox objects are axis-aligned bounding box volumes.

Constructors

The BoundingBox object defines the following constructors. 

public BoundingBox()
public BoundingBox(Point3d lower, Point3d upper)
public BoundingBox(Bounds boundsObject)
public BoundingBox(Bounds bounds[])

The first constructor constructs and initializes a 2X unity BoundingBox about the origin. The second constructor constructs and initializes a BoundingBox from the given minimum and maximum in x, y, and z. The third constructor constructs and initializes a BoundingBox from a bounding object. The fourth constructor constructs and initializes a BoundingBox from an array of bounding objects.

Methods

The BoundingBox object defines the following methods. 

public void getLower(Point3d p1)
public void setLower(Point3d p1)
public void setLower(double xmin, double ymin, double zmin)

This parameter specifies the lower corner of this bounding box. 

public void getUpper(Point3d p1)
public void setUpper(Point3d p1)
public void setUpper(double xmax, double ymax, double zmax)

This parameter specifies the upper corner of this bounding box. 

public void set(Bounds boundsObject)

Sets the value of this bounding region to enclose the specified bounding object. 

public Object clone()

Creates a copy of this bounding box. 

public void combine(Bounds boundsObject)
public void combine(Bounds[] boundsObjects)
public void combine(Point3d point)
public void combine(Point3d[] points)

These methods combine this bounding box with a bounding object, an array of bounding objects, a point, or an array of points, respectively. 

public void transform(Bounds boundsObject, Transform3D matrix)
public void transform(Transform3D matrix)

The first method transforms a bounding box so that it bounds a volume which is the result of transforming the given bounding object with the given transform. The second method transforms the bounding box by the given matrix. 

public boolean intersect(Point3d origin, Vector3d direction)
public boolean intersect(Point3d point)
public boolean intersect(Bounds boundsObject)
public boolean intersect(Bounds[] boundsObjects)

These methods test for the intersection of this bounding box with a ray, a point, another bounds object, an array of bounds objects, another bounding box, and an array of bounds objects, respectively. 

public boolean intersect(Bounds boundsObject, 
       BoundingBox  newBoundBox)
public boolean intersect(Bounds[] boundsObjects, 
       BoundingBox  newBoundBox)

These methods compute a new BoundingBox which bounds the volume created by the intersection of this BoundingBox with another bounds object, or array of bounds objects. 

public abstract boolean isEmpty()

This method tests if any objects are in a bounding box.

7.1.25 BoundingSphere Object

The BoundingSphere object defines a spherical bounding volume. It has two associated values, the center point and the radius of the sphere.

Constructors

The BoundingSphere object defines the following constructors. 

public BoundingSphere()
public BoundingSphere(Point3D center, double radius)
public BoundingSphere(Bounds boundsObject)
public BoundingSphere(Bounds[] boundsObjects)

The first constructor constructs and initializes a BoundingSphere to unity(radius = 1.0 and center at 0.0, 0.0, 0.0). The second constructor constructs and initializes a BoundingSphere from a center and radius. The third constructor constructs and initializes a BoundingSphere from a bounding object. The fourth constructor constructs and initializes a BoundingSphere from an array of bounding objects.

Methods

The BoundingSphere object defines the following methods. 

public double getRadius()
public void setRadius(double r)

This parameter specifies the bounding sphere radius. 

public void getCenter(Point3d center)
public void setCenter(Point3d center)

This parameter defines the position of the bounding sphere. 

public void set(Bounds boundsObject)

Sets the value of this bounding sphere to enclose the volume specified by the bounds object. 

public Object clone()

Clone this object. 

public void combine(Bounds boundsObject)
public void combine(Bounds[] boundsObjects)
public void combine(Point3d point)
public void combine(Point3d[] points)

These methods combine this bounding sphere with a bounding object, an array of bounding objects, a point, or an array of points, respectively. 

public boolean intersect(Point3d origin, Vector3d direction)
public boolean intersect(Point3d point)
public boolean intersect(Bounds boundsObject)
public boolean intersect(Bounds[] boundsObjects)

These methods test for the intersection of this bounding sphere with the given bounding sphere, bounding box, ray, point, another bounds object, or an array of bounds objects. 

public boolean intersect(Bounds boundsObject, 
       BoundingSphere  newBoundSphere)
public boolean intersect(Bounds[] boundsObjects, 
       BoundingSphere  newBoundSphere)

These methods compute a new BoundingSphere which bounds the volume created by the intersection of this BoundingSphere with another bounds object, or array of bounds objects. 

public void transform(Bounds bounds, Transform3D trans)
public void transform(Transform3D matrix)

The first method tranforms a bounding sphere so that it bounds a volume which is the result of transforming the given bounding object with the given transform. The second method transforms the bounding sphere by the given matrix. Note that when transforming a bounding sphere by a transformation matrix containing a non-uniform scale or a shear, the result is a bounding sphere with a radius equal to the maximal scale in any direction-the bounding sphere does not transform into an ellipsoid. 

public String toString()

This method returns a string representation of this class. 

public abstract boolean isEmpty()

This method tests if any objects are in a bounding sphere.

7.1.26 BoundingPolytope Object

A BoundingPolytope object defines a set of planes that prescribe a convex, closed polygonal bounding region.

Constructors

The BoundingPolytope object defines the following constructors. 

public BoundingPolytope()
public BoundingPolytope(Vector4d[] planes)
public BoundingPolytope(Bounds boundsObject)
public BoundingPolytope(Bounds[] boundsObjects)

The first constructor constructs a new BoundingPolytope object and initializes it to a cube where -1 = x,y,x 1. The second constructor constructs and initializes a BoundingPolytope from an array of bounding planes. The third constructor constructs and initializes a BoundingPolytope from a bounds object. The final constructor constructs and initializes a BoundingPolytope from an array of bounds objects.

Methods

The BoundingPolytope object defines the following methods. 

public void setPlanes(Vector4d[] planes)
public void getPlanes(Vector4d[] planes)

These methods set and retrieve the bounding planes for this BoundingPolytope object. 

public void set(Bounds boundsObject)

This method sets the planes for this BoundingPolytope by keeping its current number and direction of the planes and computing new plane positions to enclose the given bounds object. 

public Object clone()

This method creates a copy of the BoundingPolytope object. 

public void combine(Bounds boundsObject)
public void combine(Bounds[] boundsObjects)
public void combine(Point3d point)
public void combine(Point3d[] points)

These methods combine this BoundingPolytope with a bounding object, an array of bounding objects, a point, or an array of points, respectively. 

public void transform(Bounds bounds, Transform3D trans)
public void transform(Transform3D matrix)

The first method tranforms a bounding polytope so that it bounds a volume which is the result of transforming the given bounding object with the given transform. The second method transforms the bounding sphere by the given matrix. 

public boolean intersect(Point3d origin, Vector3d direction)
public boolean intersect(Point3d point)
public boolean intersect(Bounds boundsObject)
public boolean intersect(Bounds[] boundsObjects)

These methods test for the intersection of this BoundingPolytope with the given ray, point, another bounds object, or array of bounds objects, respectively. 

public boolean intersect(Bounds boundsObject, 
       BoundingPolytope  newBoundPolytope)
public boolean intersect(Bounds[] boundsObjects, 
       BoundingPolytope  newBoundPolytope)

These methods compute a new BoundingPolytope which bounds the volume created by the intersection of this BoundingPolytope with another bounds object, or array of bounds objects. 

public abstract boolean isEmpty()

This method tests if any objects are in a bounding polytope.

7.1.27 Transform3D Object

Transformations are represented by matrix multiplication and include such operations as rotation, scaling, and translation. The Transform3D object is represented internally as a 4 x 4 double-precision floating point matrix. The mathematical representation is row major, as in traditional matrix mathematics.

Constants
public static final int ZERO
public static final int IDENTITY
public static final int SCALE
public static final int TRANSLATION
public static final int ORTHOGONAL
public static final int RIGID
public static final int CONGRUENT
public static final int AFFINE
public static final int NEGATIVE_DETERMINANT

A Transform3D has an associated type that is internally computed when the transform is constructed and updated any time it is modified. A matrix will typically have multiple types. For example, the type associated with an identity matrix is the result of ORing all of the types, except for ZERO (and NEGATIVE_DETERMINANT), together. There are public methods available to get the ORed type of the transform, the sign of the determinant, and the least general matrix type. The matrix type flags are defined as follows:

A matrix is also classified by the sign of its determinant:

The Java 3D model for 4 x 4 transforms is:

x' = m00 · x + m01 · y + m02 · z + m03 · w
y' = m10 · x + m11 · y + m12 · z + m13 · w
z' = m20 · x + m21 · y + m22 · z + m23 · w
w' = m30 · x + m31 · y + m32 · z + m33 · w

Note: When transforming a Point3f or a Point3d, the input w is set to 1. When transforming a Vector3f or Vector3d, the input w is set to 0.
Constructors

The Transform3D object defines the following constructors. 

public Transform3D()

Constructs and initializes a new transform to identity. 

public Transform3D(Transform3D t1)

Construct and initializes a new transform from the Transform3D object. 

public Transform3D(Matrix3f m1, Vector3d t1, double s)
public Transform3D(Matrix3d m1, Vector3d t1, double s)
public Transform3D(Matrix3f m1, Vector3f t1, float s)

These construct and initialize a new transform from the rotation matrix, translation, and scale values. The scale is applied only to the rotational component of the matrix (upper 3 x 3) and not to the translational components of the matrix. 

public Transform3D(Matrix4f m1)
public Transform3D(Matrix4d m1)

These construct and initialize a new transform from the 4 x 4 matrix. The type of the constructed transform is classified automatically. 

public Transform3D(float matrix[])
public Transform3D(double matrix[])

These construct and initialize a new transform from the array of length 16. The top row of the matrix is initialized to the first four elements of the array, and so on. The type of the constructed transform is classified internally. 

public Transform3D(Quat4d q1, Vector3d t1, double s)
public Transform3D(Quat4f q1, Vector3d t1, double s)
public Transform3D(Quat4f q1, Vector3f t1, float s)

These construct and initialize a new transform from the quaternion q1, the translation t1, and the scale s. The scale is applied only to the rotational components of the matrix (the upper 3 x 3) and not to the translational components of the matrix. 

public Transform3D(GMatrix m1)

This constructs and initializes a new transform and initializes it to the upper 4 x 4 of the GMatrix argument. If the parameter matrix is smaller than 4 x 4, the remaining elements in the transform matrix are assigned to zero.

Methods

The Transform3D object defines the following methods. 

public final int getType()

This method retrieves the type of this matrix. The type is an ORed bitmask of all of the type classifications to which it belongs. 

public final int getBestType()

This method retrieves the least-general type of this matrix. 

public final void setAutoNormalize(boolean autoNormalize)
public final boolean getAutoNormalize()

These methods set and retrieve the state of auto-normalization. Auto normalization performs an automatic SVD normalization of the rotational components (upper 3 x 3) of this matrix after every subsequent matrix operation on this object, unless the boolean is subsequently set to false. The default value for this parameter is false. 

public final boolean getDeterminantSign()

This method returns the sign of the determinant of this matrix. A return value of true indicates a positive determinant. A return value of false indicates a negative determinant. In general, an orthogonal matrix with a positive determinant is a pure rotation matrix; an orthogonal matrix with a negative determinant is both a rotation and a reflection matrix. 

public final void setIdentity()

This method sets this transform to the identity matrix. 

public final void setZero()

This method sets this transform to all zeros. 

public final void setEuler(Vector3d euler)

This method sets the rotational component (upper 3 x 3) of this transform to the rotation matrix converted from the Euler angles provided. The euler parameter is a Vector3d consisting of roll, pitch, and yaw. 

public final void setRotation(Matrix3d m1)
public final void setRotation(Matrix3f m1)

These methods set the rotational component (upper 3 x 3) of this matrix to the matrix values in the double precision Matrix3d argument; the other elements of this matrix are unchanged. A singular value decomposition (SVD) is performed on this object's upper 3 x 3 matrix to factor out the scale, then this object's upper 3 x 3 matrix components are replaced by the passed rotation components, and then the scale is reapplied to the rotational components. 

public final void setRotation(Quat4f q1)
public final void setRotation(Quat4d q1)

These methods set the rotational component (upper 3 x 3) of this matrix to the matrix equivalent values of the quaternion argument; the other elements of this matrix are unchanged. A singular value decomposition is performed on this object's upper 3 x 3 matrix to factor out the scale, then this object's upper 3x3 matrix components are replaced by the matrix equivalent of the quaternion, and then the scale is reapplied to the rotational components. 

public final void setRotation(AxisAngle4d a1)
public final void setRotation(AxisAngle4f a1)

These methods set the rotational component (upper 3 x 3) of this matrix to the matrix equivalent values of the axis-angle argument; the other elements of this matrix are unchanged. A singular value decomposition is performed on this object's upper 3 x 3 matrix to factor out the scale, then this object's upper 3 x 3 matrix components are replaced by the matrix equivalent of the axis-angle, and then the scale is reapplied to the rotational components. 

public final void setScale(double scale)
public final double getScale()

The set method sets the scale component of the current matrix by factoring out the current scale from the rotational component and multiplying by the new scale. The get method performs an SVD normalization of this transform to calculate and return the scale factor; this transform is not modified. 

public final void scaleAdd(double s, Transform3D t1, 
       Transform3D  t2)
public final void scaleAdd(double s, Transform3D t1)

The first method scales transform t1 by a uniform scale matrix with scale factor s then adds transform t2 (this = S*t1 + t2). The second method scales this transform by a uniform scale matrix with scale factor s then adds transform t1 (this = S*this + t1). 

public final void setNonUniformScale(double xScale, 
       double  yScale, double zScale)

This method replaces the current transform with a non-uniform scale transform. All values of the existing transform are replaced. 

public final void setRotationScale(Matrix3f m1)
public final void setRotationScale(Matrix3d m1)
public final void getRotationScale(Matrix3f m1)
public final void getRotationScale(Matrix3d m1)

The set methods replace and retrieve the upper 3 x 3 matrix values of this transform with the values in the matrix m1. The get methods retrieve the upper 3 x 3 matrix values of this transform and place them in the matrix m1. 

public String toString()

This method returns the matrix elements of this transform as a string. 

public final void add(Transform3D t1)
public final void add(Transform3D t1, Transform3D t2)
public final void sub(Transform3D t1)
public final void sub(Transform3D t1, Transform3D t2)

The first add method adds this transform to the transform t1 and places the result back into this. The second add method adds the transforms t1 and t2 and places the result into this. The first sub method subtracts transform t1 from this transform and places the result back into this. The second sub method subtracts transform t2 from t1 and places the result into this. 

public final void transpose()
public final void transpose(Transform3D t1)

The first method transposes this matrix in place. The second method transposes transform t1 and places the value into this transform. The transform t1 is not modified. 

public void rotX(double angle)
public void rotY(double angle)
public void rotZ(double angle)

These three methods set the value of this matrix to a rotation matrix about the specified axis. The angle to rotate is specified in radians. 

public final void setTranslation(Vector3f trans)
public final void setTranslation(Vector3d trans)

This method modifies the translational components of this transform to the values of the argument. The other values of this transform are not modified. 

public final void set(Quat4f q1)
public final void set(Quat4d q1)

These methods set the value of this transform to the matrix conversion of the quaternion argument. 

public final void set(Quat4d q1, Vector3d t1, double s)
public final void set(Quat4f q1, Vector3d t1, double s)
public final void set(Quat4f q1, Vector3f t1, float s)

These methods set the value of this matrix from the rotation expressed by the quaternion q1, the translation t1, and the scale s. 

public final void set(Vector3d trans)
public final void set(Vector3f trans)

These methods set the translational value of this matrix to the passed vector parameter values and set the other components of the matrix as if this transform were an identity matrix. 

public final void set(Vector3d v1, double scale)
public final void set(Vector3f v1, float scale)

These methods set the value of this transform to a scale and translation matrix; the translation is scaled by the scale factor and all of the matrix values are modified. 

public final void set(Transform3D t1)

This method sets the matrix, type, and state of this transform to the matrix, type, and state of the transform t1. 

public final void set(double matrix[])
public final void set(float matrix[])

These methods set the matrix values of this transform to the passed matrix values. 

public final void set(double scale)
public final void set(double scale, Vector3d v1)
public final void set(float scale, Vector3f v1)

The first method sets the value of this transform to a uniform scale; all of the matrix values are modified. The next two methods set the value of this transform to a scale and translation matrix; the scale is not applied to the translation and all of the matrix values are modified. 

public final void set(Matrix4d m1)
public final void set(Matrix4f m1)

These methods set the matrix values of this transform to the matrix values in the passed argument. 

public final void set(Matrix3f m1)
public final void set(Matrix3d m1)

These methods set the rotational component (upper 3 x 3) of this transform to the matrix values in the passed argument. 

public final void set(Matrix3f m1, Vector3f t1, float s)
public final void set(Matrix3f m1, Vector3d t1, double s)
public final void set(Matrix3d m1, Vector3d t1, double s)

These methods set the value of this matrix from the rotation expressed by the rotation matrix m1, the translation t1, and the scale s. The scale is only applied to the rotational component of the matrix (upper 3 x 3) and not to the translational component of the matrix. 

public final void set(GMatrix matrix)

These methods set the matrix values of this transform to the matrix values in the passed argument. The GMatrix object must specify a 4 x 4, 3 x 4, or 3 x 3 matrix. 

public final void set(AxisAngle4f a1)
public final void set(AxisAngle4d a1)

These methods set the value of this transform to the matrix conversion of the double precision axis-angle argument; only the upper 3 x 3 of this transform is modified. 

public final void get(double matrix[])
public final void get(float matrix[])
public final void get(Matrix3d) m1)
public final void get(Matrix3f m1)
public final void get(Matrix4d matrix)
public final void get(Matrix4f matrix)

These methods place the values of this transform into the specified matrix. 

public final double get(Matrix3d m1, Vector3d t1)
public final float get(Matrix3f m1, Vector3f t1)
public final double get(Matrix3f m1, Vector3d t1)

These methods perform an SVD normalization of this matrix to calculate the rotation as a 3 x 3 matrix, the translation, and the scale. None of the matrix values are modified. 

public final void get(Quat4d q1)
public final void get(Quat4f q1)

These methods perform an SVD normalization of this matrix to acquire the normalized rotational component. The values are placed into the quaternion q1 parameter. 

public final double get((Quat4d q1, Vector3d t1)
public final float get(Quat4f q1, Vector3f t1)
public final double get(Quat4f q1, Vector3d t1)

These methods perform an SVD normalization of this matrix to calculate the rotation as a quaternion, the translation, and the scale. None of the matrix values are modified. 

public final void get(Vector3d trans)
public final void get(Vector3f trans)

These methods retrieve the translational components of this transform. 

public final void invert()
public final void invert(Transform3D t1)

The first method inverts this transform in place. The second method sets the value of this transform to the inverse of the passed Transform3D parameter. Both of these methods use the transform type to determine the optimal algorithm for inverting the transform. 

public final double determinant()

This method calculates and returns the determinant of this transform. 

public final void mul(Transform3D t1)
public final void mul(Transform3D t1, Transform3D t2)

The first method sets the value of this transform to the result of multiplying itself with transform t1 (this = this * t1). The second method sets the value of this transform to the result of multiplying transform t1 by transform t2 (this = t1*t2). 

public final void mul(double scalar)
public final void mul(double scalar, Transform3D t1)

The first method multiplies this transform by the scalar constant. The second method multiplies transform t1 by the scalar constant and places the value into this transform. 

public final void mulInverse(Transform3D t1)
public final void mulInverse(Transform3D t1, Transform3D t2)

The first method multiplies this transform by the inverse of transform t1 and places the result into this matrix (this = this * t1-1). The second method multiplies transform t1 by the inverse of transform t2 and places the result into this matrix (this = t1 * t2-1). 

public final void mulTransposeRight(Transform3D t1, 
       Transform3D  t2)
public final void mulTransposeLeft(Transform3D t1, 
       Transform3D  t2)
public final void mulTransposeBoth(Transform3D t1, 
       Transform3D  t2)

The first method multiplies the transform t1 by the transpose of transform t2 and places the result into this transform (this = t1 · transpose(t2)). The second method multiplies the transpose of transform t1 by transform t2 and places the result into this matrix (this = transpose(t1) · t2). The third method multiplies the transpose of transform t1 by the transpose of t2 and places the result into this transform (this = transpose(t1) · trasnspose(t2)). 

public final void normalize()
public final void normalize(Transform3D t1)

Both of these methods use a Singular Value Decomposition (SVD) normalization. The first normalize method normalizes the rotational components (upper 3 x 3) of matrix this and places the results back into this. The second normalize method normalizes the rotational components (upper 3 x 3) of transform t1 and places the result in this. 

public final void normalizeCP()
public final void normalizeCP(Transform3D t1)

Both of these methods use a cross product (CP) normalization. The first normalizeCP method normalizes the rotational components (upper 3 x 3) of this transform and places the result into this transform. The second normalizeCP method normalizes the rotational components (upper 3 x 3) of transform t1 and places the result into this transform. 

public boolean equals(Transform3D t1)

This method returns true if all of the data members of transform t1 are equal to the corresponding data members in this Transform3D. 

public boolean epsilonEquals(Transform3D t1, double epsilon)

This method returns true if the L-infinite distance between this matrix and matrix m1 is less than or equal to the epsilon parameter, otherwise returns false. The L-infinite distance is equal to MAX[i=0,1,2,3 ; j=0,1,2,3 ; abs[(this.m(i,j) - m1.m(i,j)]. 

public int hashCode()

This method returns a hash number based on the data values in this object. Two different Transform3D objects with identical data values (i.e., returns true for trans.equals(Transform3D)) will return the same hash number. Two Transform3Ds with different data members may return the same hash value, although this is not likely. 

public final void transform(Vector4d vec, vector4d vecOut)
public final void transform(Vector4f vec, Vector4f vecOut)
public final void transform(Vector4d vec)
public final void transform(Vector4f vec)

The first two methods transform the vector vec using this transform and place the result into vecOut. The last two methods transform the vector vec using this transform and place the result back into vec. 

public final void transform(Point3d point, Point3d pointOut)
public final void transform(Point3f point, point3f pointOut)
public final void transform(Point3d point)
public final void transform(Point3f point)

The first two methods transform the point parameter with this transform and place the result into pointOut. The last two methods transform the point parameter with this transform and place the result back into point. In both cases, the fourth element of the point input parameter is assumed to be one. 

public final void transform(Vector3d normal, Vector3d normalOut)
public final void transform(Vector3f normal, Vector3f normalOut)
public final void transform(Vector3d normal)
public final void transform(Vector3f normal)

The first two methods transforms the normal parameter by this transform and place the value into normalOut. The third and fourth methods transform the normal parameter by this transform and place the value back into normal.

7.1.27.1 View Model Compatibility Mode Methods-Viewing Matrix

public void lookAt(Point3d eye, Point3d center, Vector3d up)

This is a utility method that specifies the position and orientation of a viewing transform. It works very similarly to the similar function in OpenGL. The inverse of this transform can be used to control the ViewPlatform object within the scene graph. Alternatively, this transform can be passed directly to the View's VpcToEc transform via the compatibility mode viewing functions defined in Section C.11.2, "Using the Camera-based View Model."

7.1.27.2 View Model Compatibility Mode Methods-Projection Matrix

public void frustum(double left, double right, double bottom, 
       double top, double near, double far)
public void perspective(double fovy, double aspect, double zNear, 
       double zFar)
public void ortho(double left, double right, double bottom, 
       double top, double near, double far)

These three utility methods allow an application to create a perspective or parallel (orthographic) projection matrix. These three methods work very similarly to the similar functions in OpenGL. The resulting Transform3D can be used to directly set the View's left and right projection transforms when in compatibility mode. See Section C.11.2, "Using the Camera-based View Model," for details. The fovy parameter specifies the field of view in the y direction in radians.

7.2 Node Component Objects-Geometry

A Geometry object is an abstract class that specifies the geometry component information required by a Shape3D node. Geometry objects describe both the geometry and topology of the Shape3D nodes that reference them. Geometry objects consist of four generic geometric types: CompressedGeometry, GeometryArray, Raster, and Text3D. Each of these geometric types define a visible object or set of objects. A Geometry object is used as a component object of a Shape3D leaf node.

7.2.1 GeometryArray Object

A GeometryArray object is an abstract class from which several classes are derived to specify a set of geometric primitives. A GeometryArray contains separate arrays of the following vertex components: coordinates, colors, normals and texture coordinates, and a bitmask indicating which of these components are present.

A single GeometryArray contains a predefined collection of per-vertex information; all of the vertices in a GeometryArray object have the same format and primitive type. Different GeometryArrays can contain different per-vertex information. One GeometryArray might contain only three-space coordinates; another might contain per-vertex coordinates, normals, colors, and texture coordinates; yet, another might contain any subset of the previous example.

Constants

The GeometryArray object defines the following flags. 

public static final int ALLOW_COORDINATE_READ
public static final int ALLOW_COORDINATE_WRITE

These flags specify that the GeometryArray object allows reading or writing of the array of coordinates. 

public static final int ALLOW_COLOR_READ
public static final int ALLOW_COLOR_WRITE

These flags specify that the GeometryArray object allows reading or writing the array of colors. 

public static final int ALLOW_NORMAL_READ
public static final int ALLOW_NORMAL_WRITE

These flags specify that the GeometryArray object allows reading or writing the array of normals. 

public static final int ALLOW_TEXCOORD_READ
public final static int ALLOW_TEXCOORD_WRITE

These flags specify that the GeometryArray object allows reading or writing of the array of texture coordinates.

Constructors

The GeometryArray object has the following constructor. 

public GeometryArray(int vertexCount, int vertexFormat)

Constructs an empty GeometryArray object with the specified number of vertices, and vertex format. The vertexCount parameter specifies the number of vertex elements in this array. The vertexFormat parameter is a mask indicating which vertex components are present in each vertex. The vertex format is specified as a set of flags which are bitwise OR-ed together to describe the per-vertex data. The following vertex formats are supported:

Methods

GeometryArray methods provide access (gets and sets) to individual vertex component arrays in two different modes: as individual elements or as arrays of multiple elements. 

public final int getVertexCount()

Retrieves the number of vertices in the GeometryArray. 

public final int getVertexFormat()

Retrieves the vertexFormat in the GeometryArray. 

public final void setCoordinate(int index, float coordinate[])
public final void getCoordinate(int index, float coordinate[])
public final void setCoordinate(int index, double coordinate[])
public final void getCoordinate(int index, double coordinate[])

Sets or retrieves the coordinate associated with the vertex at the specified index. The coordinate parameter is an array of three values containing the new coordinate. 

public final void setCoordinate(int index, Point3f coordinate)
public final void getCoordinate(int index, Point3f coordinate)
public final void setCoordinate(int index, Point3d coordinate)
public final void getCoordinate(int index, Point3d coordinate)

Sets or retrieves the coordinate associated with the vertex at the specified index. The coordinate parameter is a point containing the new coordinate. 

public final void setCoordinates(int index, float coordinates[])
public final void getCoordinates(int index, float coordinates[])
public final void setCoordinates(int index, double coordinates[])
public final void getCoordinates(int index, double coordinates[])

Sets or retrieves the coordinates associated with the vertices starting at the specified index. The coordinates parameter is an array of 3*n values containing n new coordinates. 

public final void setCoordinates(int index, 
       Point3f  coordinates[])
public final void getCoordinates(int index, 
       Point3f  coordinates[])
public final void setCoordinates(int index, 
       Point3d  coordinates[])
public final void getCoordinates(int index, 
       Point3d  coordinates[])

Sets or retrieves the coordinates associated with the vertices starting at the specified index. The coordinates parameter is an array of points containing new coordinates. 

public final void setCoordinates(int index, 
       Point3d  coordinates[], int start, int length)
public final void setCoordinates(int index, 
       Point3f  coordinates[], int start, int length)
public final void setCoordinates(int index, float coordinates[], 
       int start, int length)
public final void setCoordinates(int index, double coordinates[], 
       int start, int length)

These methods set the coordinates associated with the vertices starting at the specified index for this object using coordinate data starting from vertex index start for length vertices. 

public final void setColor(int index, float color[])
public final void getColor(int index, float color[])
public final void setColor(int index, byte color[])
public final void getColor(int index, byte color[])

Sets or retrieves the color associated with the vertex at the specified index. The color parameter is an array of three or four values containing the new color. 

public final void setColor(int index, Color3f color)
public final void getColor(int index, Color3f color)
public final void setColor(int index, Color4f color)
public final void getColor(int index, Color4f color)
public final void setColor(int index, Color3b color)
public final void getColor(int index, Color3b color)
public final void setColor(int index, Color4b color)
public final void getColor(int index, Color4b color)

Sets or retrieves the color associated with the vertex at the specified index. The color parameter is a array containing the new color. 

public final void setColors(int index, float colors[])
public final void getColors(int index, float colors[])
public final void setColors(int index, byte colors[])
public final void getColors(int index, byte colors[])

Sets or retrieves the colors associated with the vertices starting at the specified index. The colors parameter is an array of 3*n or 4*n values containing n new colors. 

public final void setColors(int index, Color3f colors[])
public final void getColors(int index, Color3f colors[])
public final void setColors(int index, Color4f colors[])
public final void getColors(int index, Color4f colors[])
public final void setColors(int index, Color3b colors[])
public final void getColors(int index, Color3b colors[])
public final void setColors(int index, Color4b colors[])
public final void getColors(int index, Color4b colors[])

Sets or retrieves the colors associated with the vertices starting at the specified index. The colors parameter is an array containing the new colors. 

public final void setColors(int index, float colors[], int  start, 
       int length)
public final void setColors(int index, byte colors[], int start, 
       int length)
public final void setColors(int index, Color3f colors[], 
       int  start, int length)
public final void setColors(int index, Color4f colors[], 
       int  start, int length)
public final void setColors(int index, Color3b colors[], 
       int  start, int length)
public final void setColors(int index, Color4b colors[], 
       int  start, int length)

These methods set the colors associated with the vertices starting at the specified index for this object using data in colors starting at index start for length colors. 

public final void setNormal(int index, float normal[])
public final void getNormal(int index, float normal[])

Sets or retrieves the normal associated with the vertex at the specified index. The normal parameter is an array of three values containing the new normal. 

public final void setNormal(int index, Vector3f normal)
public final void getNormal(int index, Vector3f normal)

Sets or retrieves the normal associated with the vertex at the specified index. The normal parameter is a vector containing the new normal. 

public final void setNormals(int index, float normals[])
public final void getNormals(int index, float normals[])

Sets or retrieves the normals associated with the vertices starting at the specified index. The normals parameter is an array of 3*n values containing n new normals. 

public final void setNormals(int index, Vector3f normals[])
public final void getNormals(int index, Vector3f normals[])

Sets or retrieves the normals associated with the vertices starting at the specified index. The normals parameter is an array of vectors containing new normals. 

public final void setNormals(int index, float normals[], 
       int  start, int length)
public final void setNormals(int index, Vector3f normals[], 
       int  start, int length)

These methods set the normals associated with the vertices starting at the specified index for this object using data in normals starting at index start and ending at index start+length. 

public final void setTextureCoordinate(int index, 
       float  texCoord[])
public final void getTextureCoordinate(int index, 
       float  texCoord[])

Sets or retrieves the texture coordinate associated with the vertex at the specified index. The texCoord parameter is an array of two or three values containing the new texture coordinate. 

public final void setTextureCoordinate(int index, 
       Point2f  texCoord)
public final void getTextureCoordinate(int index, 
       Point2f  texCoord)
public final void setTextureCoordinate(int index, 
       Point3f  texCoord)
public final void getTextureCoordinate(int index, 
       Point3f  texCoord)

Sets or retrieves the texture coordinate associated with the vertex at the specified index. The texCoord parameter is a point containing the new texture coordinate. 

public final void setTextureCoordinates(int index, 
       float  texCoords[])
public final void getTextureCoordinates(int index, 
       float  texCoords[])

Sets or retrieves the texture coordinates associated with the vertices starting at the specified index. The texCoords parameter is an array of 2*n or 3*n values containing n new texture coordinates. 

public final void setTextureCoordinates(int index, 
       Point2f  texCoords[])
public final void getTextureCoordinates(int index, 
       Point2f  texCoords[])
public final void setTextureCoordinates(int index, 
       Point3f  texCoords[])
public final void getTextureCoordinates(int index, 
       Point3f  texCoords[])

Sets or retrieves the texture coordinates associated with the vertices starting at the specified index. The texCoords parameter is an array of points containing the new texture coordinate. 

public final void setTextureCoordinates(int index, 
       float  texCoords[], int start, int length)
public final void setTextureCoordinates(int index, 
       Point2f  texCoords[], int start, int length)
public final void setTextureCoordinates(int index, 
       Point3f  texCoords[], int start, int length)

These methods set the texture coordinates associated with the vertices starting at the specified index for this object using data in texCoords starting at index start and ending at index start+length.

7.2.2 PointArray Object

The PointArray object extends GeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual points.

Constructors
public PointArray(int vertexCount, int vertexFormat)

Constructs an empty PointArray object with the specified number of vertices and vertex format.

7.2.3 LineArray Object

The LineArray object extends GeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual line segments. Each pair of vertices defines a line segment to be drawn.

Constructors
public LineArray(int vertexCount, int vertexFormat)

Constructs an empty LineArray object with the specified number of vertices and vertex format.

7.2.4 TriangleArray Object

The TriangleArray object extends GeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual triangles. Each group of three vertices defines a triangle to be drawn.

Constructors
public TriangleArray(int vertexCount, int vertexFormat)

Constructs an empty TriangleArray object with the specified number of vertices and vertex format.

7.2.5 QuadArray Object

The QuadArray object extends GeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual quadrilaterals. Each group of four vertices defines a quadrilateral to be drawn. A quadrilateral must be planar and convex or results are undefined. A quadrilateral may be rendered as a pair of triangles with either diagonal line arbitrarily chosen to split the quad.

Constructors
public QuadArray(int vertexCount, int vertexFormat)

Constructs an empty QuadArray object with the specified number of vertices and vertex format.

7.2.6 GeometryStripArray Object

GeometryStripArray is an abstract class from which all strip primitives (line strip, triangle strip and triangle fan) are derived. In addition to specifying the array of vertex elements, which is inherited from GeometryArray, the GeometryStripArray class specifies a number of strips and an array of per-strip vertex counts that specifies where the separate strips appear in the vertex array.

Constructors

The GeometryStripArray object has the following constructor. 

public GeometryStripArray(int vertexCount, int vertexFormat, 
       int[] stripVertexCounts)

Constructs an empty GeometryStripArray object with the specified number of vertices, vertex format, and an array of vertex counts per strip. The vertexCount parameter specifies the number of vertex elements in this array.

The stripVertexCounts parameter is an array that specifies the count of the number of vertices for each separate strip. The length of this array specifies the number of separate strips. The sum of the vertex counts for all strips, as specified by the stripVertexCounts array, must equal the total count of all vertices as specified by the vertexCount parameter.

Methods

The GeometryStripArray object has the following methods. 

public final int getNumStrips()

This method returns the number of strips in the GeometryStripArray. 

public final void getStripVertexCounts(int stripVertexCounts)

This method gets a list of vertexCounts for each strip.

7.2.7 LineStripArray Object

The LineStripArray extends GeometryStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected line strips. An array of per-strip vertex counts specifies where the separate strips appear in the vertex array. For every strip in the set, each vertex, beginning with the second vertex in the array, defines a line segment to be drawn from the previous vertex to the current vertex.

Constructors
public LineStripArray(int vertexCount, int vertexFormat, 
       int[]  stripVertexCounts)

Constructs an empty LineStripArray object with the specified number of vertices, vertex format, and array of vertex counts per strip.

7.2.8 TriangleStripArray Object

The TriangleStripArray extends GeometryStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected triangle strips. An array of per-strip vertex counts specifies where the separate strips appear in the vertex array. For every strip in the set, each vertex, beginning with the third vertex in the array, defines a triangle to be drawn using the current vertex and the two previous vertices.

Constructors
public TriangleStripArray(int vertexCount, int vertexFormat, 
       int[] stripVertexCounts)

Constructs an empty TriangleStripArray object with the specified number of vertices, vertex format, and array of vertex counts per strip.

7.2.9 TriangleFanArray Object

The TriangleFanArray extends GeometryStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected triangle fans. An array of per-strip vertex counts specifies where the separate strips (fans) appear in the vertex array. For every strip in the set, each vertex, beginning with the third vertex in the array, defines a triangle to be drawn using the current vertex, the previous vertex and the first vertex. This can be thought of as a collection of convex polygons.

Constructors
public TriangleFanArray(int vertexCount, int vertexFormat, 
       int[]  stripVertexCounts)

Constructs an empty TriangleFanArray object with the specified number of vertices, vertex format, and array of vertex counts per strip.

7.2.10 IndexedGeometryArray Object

An IndexedGeometryArray object is an abstract class that extends GeometryArray to allow vertex data to be accessed via a level of indirection. In addition to the separate arrays of coordinates, colors, normals, and texture coordinates-inherited from GeometryArray-an IndexedGeometryArray object adds corresponding arrays of coordinate indices, color indices, normal indices, and texture coordinate indices.

Constants

The IndexedGeometryArray object defines the following flags. 

public final static int ALLOW_COORDINATE_INDEX_READ
public final static int ALLOW_COORDINATE_INDEX_WRITE

These flags specify that the IndexedGeometryArray object allows reading or writing of the array of coordinate indices. 

public static final int ALLOW_COLOR_INDEX_READ
public static final int ALLOW_COLOR_INDEX_WRITE

These flags specify that the IndexedGeometryArray objects allows reading or writing of the array of color indices. 

public static final int ALLOW_NORMAL_INDEX_READ
public static final int ALLOW_NORMAL_INDEX_WRITE

These flags specify that the IndexedGeometryArray objects allows reading or writing of the array of normal indices. 

public static final int ALLOW_TEXCOORD_INDEX_READ
public static final int ALLOW_TEXCOORD_INDEX_WRITE

These flags specify that the IndexedGeometryArray objects allows reading or writing of the array of texture coordinate indices.

Constructors

The IndexedGeometryArray object has one constructor that accepts the same parameters as GeometryArray. 

public IndexedGeometryArray(int vertexCount, int vertexFormat, 
       int indexCount)

Constructs an empty IndexedGeometryArray object with the specified number of vertices, vertex format, and indices.

Methods

IndexedGeometryArray methods provide access (gets and sets) to the individual vertex component index arrays that are used when rendering the Geometry. This access is allowed in two different modes: as individual index elements or as arrays of multiple index elements. 

public final void setCoordinateIndex(int index, 
       int  coordinateIndex)
public final int getCoordinateIndex(int index)

Sets or retrieves the coordinate index associated with the vertex at the specified index. 

public final void setCoordinateIndices(int index, 
       int  coordinateIndices[])
public final void getCoordinateIndices(int index, 
       int  coordinateIndices[])

Sets or retrieves the coordinate indices associated with the vertices starting at the specified index. 

public final void setColorIndex(int index, int colorIndex)
public final int getColorIndex(int index)

Sets or retrieves the color index associated with the vertex at the specified index. 

public final void setColorIndices(int index, int colorIndices[])
public final void getColorIndices(int index, int colorIndices[])

Sets or retrieves the color indices associated with the vertices starting at the specified index. 

public final void setNormalIndex(int index, int normalIndex)
public final int getNormalIndex(int index)

Sets or retrieves the normal index associated with the vertex at the specified index. 

public final void setnormalIndices(int index, 
       int  normalIndices[])
public final void getNormalIndices(int index, 
       int  normalIndices[])

Sets or retrieves the normal indices associated with the vertices starting at the specified index. 

public final void setTextureCoordinateIndex(int index, 
       int  texCoordIndex)
public final int getTextureCoordinateIndex(int index)

Sets or retrieves the texture coordinate index associated with the vertex at the specified index. 

public final void setTextureCoordinateIndices(int index, 
       int  texCoordIndices[])
public final void getTextureCoordinateIndices(int index, 
       int  texCoordIndices[])

Sets or retrieves the texture coordinate indices associated with the vertices starting at the specified index. 

public final int getIndexCount()

Retrieves the number of indices for this IndexedGeometryArray.

7.2.11 IndexedPointArray Object

The IndexedPointArray object extends IndexedGeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual points.

Constructors

The IndexedPointArray object has the following constructor. 

public IndexedPointArray(int vertexCount, int vertexFormat, 
       int  indexCount)

Constructs an empty IndexedPointArray object with the specified number of vertices, vertex format (see Section 7.2.1, "GeometryArray Object" for a description of the supported vertex formats), and the number of indices in this array.

7.2.12 IndexedLineArray Object

The IndexedLineArray object extends IndexedGeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual line segments. Each pair of vertices defines a line segment to be drawn.

Constructors

The IndexedLineArray object has the following constructor. 

public IndexedLineArray(int vertexCount, int vertexFormat, 
       int  indexCount)

Constructs an empty IndexedLineArray object with the specified number of vertices, vertex format, and the number of indices in this array. The vertexFormat is a mask indicating which components are present in each vertex (see Section 7.2.1, "GeometryArray Object" for a description of the supported vertex formats).

7.2.13 IndexedTriangleArray Object

The IndexedTriangleArray object extends IndexedGeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual triangles. Each group of three vertices defines a triangle to be drawn.

Constructors

The IndexedTriangleArray object has the following constructor. 

public IndexedTriangleArray(int vertexCount, int vertexFormat, 
       int indexCount)

Constructs an empty IndexedTriangleArray object with the specified number of vertices, vertex format, and the number of indices in this array. The vertexFormat is a mask indicating which components are present in each vertex (see Section 7.2.1, "GeometryArray Object" for a description of the supported vertex formats).

7.2.14 IndexedQuadArray Object

The IndexedQuadArray object extends IndexedGeometryArray and provides no additional methods. Objects of this class draw the array of vertices as individual quadrilaterals. Each group of four vertices defines a quadrilateral to be drawn. A quadrilateral must be planar and convex or results are undefined. A quadrilateral may be rendered as a pair of triangles with either diagonal line arbitrarily chosen to split the quad.

Constructors

The IndexedQuadArray object has the following constructor. 

public IndexedQuadArray(int vertexCount, int vertexFormat, 
       int  indexCount)

Constructs an empty IndexedQuadArray object with the specified number of vertices, vertex format (see Section 7.2.1, "GeometryArray Objectf" for a description of the supported vertex formats), and the number of indices in this array.

7.2.15 IndexedGeometryStripArray Object

IndexedGeometryStripArray is an abstract class from which all strip primitives (line strip, triangle strip and triangle fan) are derived. In addition to specifying the array of vertex elements, which is inherited from IndexedGeometryArray, the IndexedGeometryArrayStrip class specifies a number of strips and an array of per-strip vertex counts that specifies where the separate strips appear in the vertex array.

Constructors

The IndexedGeometryStripArray object has the following constructor. 

public IndexedGeometryStripArray(int vertexCount, 
       int  vertexFormat, int indexCount, 
       int  stripVertexCounts[])

Constructs an empty IndexedGeometryStripArray object with the specified number of vertices, vertex format, number of indices in the array, and an array of vertex counts per strip. The vertexCount parameter specifies the number of vertex elements in this array. The vertexFormat parameter is a mask indicating which vertex components are present in each vertex. The indexCount parameter specifies the number of indices in this array. The stripVertexCounts parameter is an array that specifies the count of the number of vertices for each separate strip. The length of this array specifies the number of separate strips. The sum of the vertex counts for all strips, as specified by the stripVertexCounts array, must equal the total count of all vertices as specified by the vertexCount parameter.

Methods

The IndexedGeometryArrayStrip object has the following methods. 

public final int getNumStrips()

Gets the number of strips in the IndexedGeometryStripArray. 

public final void getStripIndexCounts(int stripIndexCounts[])

Gets a list of the indexCounts for each strip.

7.2.16 IndexedLineStripArray Object

The IndexedLineStripArray extends IndexedGeometryStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected line strips. An array of per-strip vertex counts specifies where the separate strips appear in the vertex array. For every strip in the set, each vertex, beginning with the second vertex in the array, defines a line segment to be drawn from the previous vertex to the current vertex.

Constructors

The IndexedLineStripArray object has the following constructor. 

public IndexedLineStripArray(int vertexCount, int vertexFormat, 
       int indexCount, int stripIndexCounts[])

Constructs an empty IndexedLineStrip object with the specified number of vertices, vertex format, number of indices in this array, and an array that specifies number of vertices for each strip. The vertexFormat parameter is a mask indicating which components are present in each vertex. This is specified as one or more individual flags that are bitwise ORed together to describe the per-vertex data (see Section 7.2.1, "GeometryArray Object" for a description of the supported vertex formats).

7.2.17 IndexedTriangleStripArray Object

The IndexedTriangleStripArray extends IndexedGeometryStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected triangle strips. An array of per-strip vertex counts specifies where the separate strips appear in the vertex array. For every strip in the set, each vertex, beginning with the third vertex in the array, defines a triangle to be drawn using the current vertex and the two previous vertices.

Constructors

The IndexedTriangleStripArray object has the following constructor. 

public IndexedTriangleStripArray(int vertexCount, 
       int  vertexFormat, int indexCount, int stripIndexCounts[])

Constructs an empty IndexedTriangleStripArray object with the specified number of vertices, vertex format, number of vertices in this array, and an array of vertex counts per strip. The vertexFormat parameter is a mask indicating which components are present in each vertex. This is specified as one or more individual flags that are bitwise ORed together to describe the per-vertex data (see Section 7.2.1, "GeometryArray Object" for a description of the supported vertex formats).

7.2.18 IndexedTriangleFanArray Object

The IndexedTriangleFanArray extends IndexedGeoStripArray and provides no additional methods. Objects of this class draw an array of vertices as a set of connected triangle fans. An array of per-strip vertex counts specifies where the separate strips (fans) appear in the vertex array. For every strip in the set, each vertex, beginning with the third vertex in the array, defines a triangle to be drawn using the current vertex, the previous vertex and the first vertex. This can be thought of as a collection of convex polygons.

Constructors

The IndexedTriangleFanArray object has the following constructor. 

public IndexedTriangleFanArray(int vertexCount, int vertexFormat, 
       int indexCount, int stripIndexCounts[])

Constructs an empty IndexedTriangleFanArray object with the specified number of vertices, vertex format, number of indices in this array, and an array of vertex counts per strip. The vertexFormat parameter is a mask indicating which components are present in each vertex. This is specified as one or more individual flags that are bitwise ORed together to describe the per-vertex data (see Section 7.2.1, "GeometryArray Object" for a description of the supported vertex formats).

7.2.19 CompressedGeometry Object

CompressedGeometry objects use a special format for representing geometric information in one order of magnitude less space. The representation, though lossy, preserves significant object quality during compression. There will be parameters to allow the user to specify the degree of lossy-ness (e.g., a space versus quality knob).

For more information, see Appendix B, "3D Geometry Compression."

Constructors
public CompressedGeometry(CompressedGeometryHeader hdr, 
       byte  geometry[])

Constructs a CompressedGeometry node component. The hdr field is copied into the CompressedGeometry object. The geometry parameter must conform to the compressed geometry format as described in Appendix B, "3D Geometry Compression."

Methods
public final int getByteCount()

Retrieves the size in bytes of the compressed geometry buffer. 

public final void 
       getCompressedGeometryHeader(CompressedGeometryHeader hdr)

Retrieves the header for this compressed geometry object. The header is copied into the CompressedGeometryHeader object provided. 

public final void getCompressedGeometry(byte compGeom[])

Retrieves the compressed geometry associated with the compressed geometry node. Copies the compressed geometry from the CompressedGeometry node into the given array. 

public final Shape3D[] decompress()

Decompresses the compressed geometry. Returns an array of Shape nodes containing the decompressed geometry objects.

7.2.20 CompressedGeometryHeader Object

The CompressedGeometryHeader node contains a description of the compressed geometry data. This header is used to aid in the processing of the compressed geometry by decompression routines. All members in the CompressedGeometryHeader node are public so no get or set routines are provided. The CompressedGeometryHeader object should be created and all values set by the geometry compression utility.

Constants
public static final int POINT_BUFFER
public static final int LINE_BUFFER
public static final int TRIANGLE_BUFFER

These flags indicate whether the compressed geometry is made up of individual points, line segments, or triangles. 

public static final int COLOR_IN_BUFFER
public static final int COLOR_ALPHA_IN_BUFFER

These flags indicate whether RGB or Alpha color information is initialized in the compressed geometry buffer. 

public int majorVersionNumber
public int minorVersionNumber
public int minorMinorVersionNumber

These indicate the major, minor, and minor-minor version numbers for the compressed geometry format that was used to compress the geometry. 

public int bufferType

This flag describes the type of data in the compressed geometry buffer. Only one type may be present in any given compressed geometry buffer. 

public int bufferDataPresent

This flag notifies that the given data type is present in the compressed geometry buffer before any geometric data. If this data is not present (i.e., color) then this information will be inherited from the Appearance node. 

public double scale
public int size
public double xOffset
public double yOffset
public double zOffset

These flags indicate the scale, size, and x, y, and z offsets needed to be applied to every point in the compressed geometry buffer to restore the geometry to its original (uncompressed) position.

Constructors
public CompressedGeometryHeader()

Creates a new CompressedGeometryHeader object used for the creation of a CompressedGeometry NodeComponent object. All instance data is declared public and no get or set methods are provided.

7.2.21 Raster Object

The Raster object extends Geometry to allow drawing a raster image that is attached to a 3D location in the virtual world. The Raster object contains a point that is defined in the local object coordinate system of the Shape3D node that references the Raster. The Raster object also contains a type specifier, a reference to a ImageComponent2D object or a DepthComponent object, and an integer x,y offset and a size (width, height) to allow reading or writing a portion of the referenced image. In addition to being used as a type of geometry for drawing, a Raster may be used to readback pixel data (color and z-buffer) from the frame buffer in immediate mode.

Constants

The Raster object defines the following flags. 

public static final int RASTER_COLOR

Specifies a Raster object with color data. In this mode, the ImageComponent reference must point to a valid ImageComponent object. 

public static final int RASTER_DEPTH

Specifies a Raster object with depth (z-buffer) data. In this mode, the depthComponent reference must point to a valid DepthComponent object. 

public static final int RASTER_COLOR_DEPTH

Specifies a Raster object with both color and depth (z-buffer) data. In this mode, the ImageComponent reference must point to a valid ImageComponent object, and the depthComponent reference must point to a valid DepthComponent object.

Constructors
public Raster()
public Raster(Pointf pos, int type, int xOffset, int yOffset, 
       int width, int height, ImageComponent2D imageComponent, 
       DepthComponent depthComponent)
public Raster(Point3f pos, int type, Point offset, 
       Dimension  size, ImageComponent2D imageComponent, 
       DepthComponent  DepthComponent)

Constructs and initializes a new Raster object. The first form uses default values. The next two forms construct a new raster image with the specified values.

Methods
public void setPosition(Point3f pos)
public void getPosition(Point3f pos)

These methods set and retrieve the position in object coordinates of this raster. This position is transformed into device coordinates and is used as the upper-left corner of the raster. 

public void setType(int type)
public int getType()

These methods set and retrieve the type of this raster object. The type is one of the following: RASTER_COLOR, RASTER_DEPTH, or RASTER_COLOR_DEPTH. 

public void setOffset(int xOffset, int yOffset)
public void setOffset(Point offset)
public void getOffset(Point offset)

These methods set and retrieve the offset within the array of pixels at which to start copying. 

public void setSize(int width, int height)
public void setSize(Dimension size)
public void getSize(Dimension size)

These methods set and retrieve the number of pixels to be copied from the pixel array. 

public void setImageComponent(ImageComponent2D image)
public ImageComponent2D getImageComponent()

These methods set and retrieve the ImageComponent used to copy pixels to/from a Canvas3D. This is used when the type is RASTER_COLOR or RASTER_COLOR_DEPTH. 

public void setDepthComponent(DepthComponent depthComponent)
public DepthComponent getDepthComponent()

These methods set and retrieve the DepthComponent used to copy pixels to or from a Canvas3D. This is used when the type is RASTER_DEPTH or RASTER_COLOR_DEPTH.

7.2.22 Font3D Object

The Font3D object is used to contain 3D glyphs used in rendering 3D text. These 3D glyphs are constructed from a Java 2D font object and a FontExtrusion object (Section 7.2.23, "FontExtrusion Object"). To ensure correct rendering, the 2D font object should be created with the default transform. The point size of the 2D font will be used as a rough measure of how fine a tesselation to use when creating the Font3D object; the larger the point size, in general, the finer the tesselation.

Constructors
public Font3D(Font font, FontExtrusion extrusionPath)

Creates a Font3D object from the specified Font object. The FontExtrusion object (see Section 7.2.23, "FontExtrusion Object") contains the extrusion path to use on the 2D Font glyphs. To ensure correct rendering, the font must be created with the default AffineTransform. The point size of a Font object is used as a rough measure of how finely to tessellate the glyphs. A larger point size will, in general, have finer detail than the same font with a smaller point size. Passing null for the FontExtrusion parameter results in no extrusion being done.

Custom 3D fonts as well as methods to save 3D fonts to disk will be addressed after the 1.0 release of this specification.

Methods
public GeometryStripArray[] getAsTriangles(int glyphCode)

This method returns an array of GeometryStripArrays representing the 3D glyph. The amount of tesselation is roughly determined by the point size used to create the 2D Font object. A larger point size will, in general, have finer detail than the same font with a smaller point size.

A 3D glyph is always defined in a normalized space where the base of the glyph is 0.0 on the y-axis and the left side of the glyph is at 0.0 on the x-axis. Because of descenders, the glyph's coordinates can be negative. The maximum value of this space is the maximum glyph width and height (obtained from FontDesignMetrics::getBounds()). 

public Bounds getBounds(int glyphCode)

This method returns the 3D bounding box of the specified glyph code. 

public Font getFont()

This method returns the Java 2D Font used to create this Font3D object. 

public void getFontExtrusion(FontExtrusion extrudePath)

This method returns the FontExtrusion object used to create this Font3D object into the specified parameter. For information about the FontExtrusion object see Section 7.2.23, "FontExtrusion Object."

7.2.23 FontExtrusion Object

The FontExtrusion object is used to describe the extrusion path for a Font3D object (see Section 7.2.22, "Font3D Object"). The extrusion path is used in conjunction with a Font2D object. The extrusion path defines the edge contour of 3D text. This contour is perpendicular to the face of the text. The contour has it's origin at the edge of the glyph with 1.0 being the height of the tallest glyph.

Constructors
public FontExtrusion()
public FontExtrusion(Shape extrusionShape)

Both of these constructors create a FontExtrusion object. The first constructor creates the object with the default extrusion shape. The default shape is a straight line from 0.0 to 0.2 (straight bevel). The second constructor creates a FontExtrusion object with the specified extrusion shape. The extrusionShape parameter is used to construct the edge contour of a Font3D object. Each shape begins with an implicit point at 0.0.

Methods
public final void setExtrusionShape(Shape extrusionShape)
public final void getExtrusionShape(Shape extrusionShape)

These methods get and set the Shape object associated with this FontExtrusion object. The Shape object describes the extrusion path used to create a 3D glyph from a 2D glyph. For the get routine, the shape is copied from the node to the given parameter. For the set routine, the given shape is copied into the FontExtrusion node.

7.2.24 Text3D Geometry Object

A Text3D object is a text string that has been converted to 3D geometry. The Font3D object (see Section 7.2.22, "Font3D Object") determines the appearance of the Text3D NodeComponent object. Each Text3D object has a text position - a point in three space where the text should be placed. The 3D text can be placed around this position using different alignments and paths.

Constants

The Text3D object defines the following flags. 

public static final int ALLOW_FONT3D_READ
public static final int ALLOW_FONT3D_WRITE
public static final int ALLOW_STRING_READ
public static final int ALLOW_STRING_WRITE
public static final int ALLOW_POSITION_READ
public static final int ALLOW_POSITION_WRITE
public static final int ALLOW_ALIGNMENT_READ
public static final int ALLOW_ALIGNMENT_WRITE
public static final int ALLOW_PATH_READ
public static final int ALLOW_PATH_WRITE

These flags control reading and writing the Font3D component information for Font3D, the String object, the text position value, the text alignment value, and the text path value.

Constructors
public Text3D()
public Text3D(Font3D font3D)
public Text3D(Font3D font3D, String string)
public Text3D(Font3D font3D, String string, Point3f position)
public Text3D(Font3D font3D, String string, Point3f position, 
       int  alignment, int path)

Create a new Text3D object. The first constructor creates the Text3D object with no Font3D object associated with it, a null string, and all default values: a position of (0.0, 0.0, 0.0), an alignment of ALIGN_FIRST, and a path of PATH_RIGHT. The other constructors set the appropriate values to the passed-in parameters.

Methods
public final Font3D getFont3D()
public final void setFont3D(Font3D font3d)

These methods get and set the Font3D object associated with this Text3D object. 

public final String getString()
public final void setString(String string)

These method get and set the character string associated with this object. The Text3D string is copied into the string provided in the get and, for the set, the given string is copied into the Text3D object. 

public final void getPosition(Point3f position)
public final void setPosition(Point3f position)

These methods get and set the text position. The position is used to determine the initial placement of the string. The text position is used in conjunction with the alignment and path to determine how the glyphs are to be placed in the scene. These values are copied into and out of the Text3D object. The default value is (0.0, 0.0, 0.0). 

public final void setAlignment(int alignment)
public final int getAlignment()

These methods set and get the text alignment policy for this Text3D NodeComponent object. The alignment is used to specify how glyphs in the string are placed in relation to the position field. Valid values for this field are:

The default value of this field is ALIGN_FIRST. 

public final void setPath(int path)
public final int getPath()

These methods set and get the node's path field. This field is used to specify how succeeding glyphs in the string are placed in relation to the previous glyph. The path is relative to the local coordinate system of the Text3D node. The default coordinate system (see Section 3.4, "Coordinate Systems") is right handed with +Y being up, +X horizontal to the right and +Z directed toward the viewer. Valid values for this field are:

The default value of this field is PATH_RIGHT. 

public final void getBoundingBox(BoundingBox bounds)

This method retrieves the 3D bounding box that encloses this Text3D object. 

public final void setCharacterSpacing(float characterSpacing)
public final float getCharacterSpacing()

These methods set and get the character spacing used to construct the Text3D string. This spacing is in addition to the regular spacing between glyphs as defined in the Font object. A value of 1.0 in this space is measured as the width of the largest glyph in the 2D Font. The default value is 0.0.

7.3 Math Component Objects

Java 3D defines a number of additional objects that are used in the construction and manipulation of other Java 3D objects. These objects provide low-level storage and manipulation control for users. They provide methods for representing vertex components (e.g., color and position), volumes, vectors, and matrices.

The tuple and matrix math classes are not part of Java 3D per se, but they are needed by Java 3D and are defined here for convenience. Java 3D uses these classes internally and also makes them available for use by applications. These classes will be delivered in a separate java.vecmath package. The tuple and matrix math classes are described in detail in Appendix A, "Math Objects."

7.3.1 Tuple Objects

The tuple objects, listed in Table 7-1, store tuples of length two, three, and four. Java 3D tuples are used to store various kinds of information such as colors, normals, texture coordinates, vertices, etc.

The tuple classes are further subdivided by storage type, such as point, vector, color, etc., and class, whether the vector consists of single or double precision floating point numbers or bytes. Only the floating-point tuple classes support math operations.

Table 7-1 Tuple Objects
Class Description
Tuple2f Used to represent two-component coordinates in single-precision floating point format. This class is further divided into the following:
  • Point2f: Represents x,y point coordinates.
  • TexCoord2f: Represents x,y texture coordinates.
  • Vector2f: Represents x,y vector coordinates.
    • Tuple3b Used to represent three-component color information stored as three bytes. This class is further divided into the following:
  • Color3b: Represents RGB color values.
    • Tuple3d Used to represent point and vector coordinates, in double-precision floating point format. This class is further divided into the following:
  • Point3d: Represents x,y,z point coordinates.
  • Vector3d: Represents x,y,z vector coordinates.
    • Tuple3f Used to represent three-component colors, point coordinates, texture coordinates, and vectors, in single-precision floating point format. This class is further divided into the following:
  • Color3f: Represents RGB color values.
  • Point3f: Represents x,y,z point coordinates.
  • TexCoord3f: Represents x,y,z texture coordinates.
  • Vector3f: Represents x,y,z vector coordinates.
    • Tuple4b Used to represent four-component color information stored as four bytes. This class is further divided into the following:
  • Color4b: Represents RGB color values.
    • Tuple4d Used to represent four-component color information, quaternions, and vectors, stored in double-precision floating point format. This class is further divided into the following:
  • Point4d: Represents x,y,z,w point coordinates.
  • Quat4d: Represents x,y,z,w quaternion coordinates.
  • Vector4d: Represents x,y,z,w vector coordinates.
    • Tuple4f Used to represent four-component color information, point coordinates, quaternions, and vectors, in single-precision floating point format. This class is further divided into the following:
  • Color4f: Represents RGB color values.
  • Point4f: Represents x,y,z,w point coordinates.
  • Quat4f: Represents x,y,z,w quaternion coordinates.
  • Vector4f: Represents x,y,z,w vector coordinates.
    • AxisAngle4d Used to represent four-component axis-angle rotations consisting of double-precision floating point x, y, and z coordinates and a rotation angle in radians.
    AxisAngle4f Used to represent four-component axis-angle rotations consisting of single-precision floating point x, y, and z coordinates and a rotation angle in radians.
    GVector Used to represent a general, dynamically-resizeable, one-dimension vector class.

    These are described in more detail in Section A.1, "Tuple Objects."

    7.3.2 Matrix Objects

    The matrix objects, listed in Table 7-2, define a complete 3 x 3 or 4 x 4 floating-point transform matrix. All the vector subclasses operate using this one matrix type.

    Table 7-2 Matrix Objects
    Class Description
    Matrix3d Used to represent a double-precision floating point 3 x 3 matrix.
    Matrix3f Used to represent a single-precision floating point 3 x 3 matrix.
    Matrix4d Used to represent a double-precision floating point 4 x 4 matrix.
    Matrix4f Used to represent a single-precision floating point 4 x 4 matrix.
    GMatrix A double-precision, general, dynamically-resizeable N x M matrix class.

    These are described in more detail in Section A.2, "Matrix Objects."


    Contents Previous Next

    Java 3D API Specification


    Copyright © 1997, Sun Microsystems, Inc. All rights reserved.